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PREFACE 



This publication describes the object- time 
PL/I Library package which forms an 
integral part of the PL/I processing 
system. General information covering the 
overall design and conventions is provided 
as well as information specific to the 
various areas of language support. 



The publication is intended primarily 
for technical personnel who wish to 
understand the structure of the library in 
order to maintain , modify, or expand the 
PL/I processing system. 

Information relevant to this manual is 
contained in the following IBM 
publications: 

IBM Svstem/360; 

Principles of Operation . Order No. 
GA22-6821 

PL/I Language Specifications . Order 
GY33-6003 

Model 91. Functional Characteristic s, 
Order No. 3A22-6907 

IBM Svstem/360 Operating System : 

Assembler Language , Order No. 
GC28-6514 

Introduction , Order No. GC28-6534 

Concepts and Facilities . Order No. 
GC28-6535 

PL/I (F) Language Reference Manual . 
Order No. GC28-8201 

Linkage Editor and Loader . Order No. 
GC28-6538 

Job Control Language User's Guide . 
Order No. 3C28-6703 

Job Control Language Referenc e. Order 
No. GC28-6704 

S ystem Prog r ammer's Guide . Order No. 
GC28-6550 



System Generation . Order No. GC28-6554 

PL/ I Subroutine Library Computational 
Subroutines . Order No. GC 28- 6 590 

PL/I (F) Programmer's Guide . Order No. 
GC28-6594 

System Control Blocks . Order No. 
GC28-6628 

Supervisor and Data Management 
Services . Order No. GC28-6646 

Sup ervisor and Data Management Macro 
Instructions . Order No. GC28-6647 

QTAM^ Message Proce s sing Program 
Servic es, Order No7 GC3 0-2003 

QTAM Message Control Program . Order No. 
GC30-2005 

PL/ 1(F) Compiler, Program Logic Manual , 
Order No. GY28-6800 

The publication includes two 
introductory chapters, 'The PL/I Library* 
and 'General Implementation Features', 
which contain a general description of the 
library as a component of IBM System/360 
Operating System, and general notes on 
features of the operating system and the 
PL/I (F) Compiler that are used in the 
library implementation. The remainder of 
the manual describes the design of the 
library modules in relationship to PL/I 
language features, and indicates the use 
that is made of the control program to 
support the design. 

The descriptive material is supported by 
a set of module description summaries and 
several appendixes. The module summaries 
indicate the salient features of individual 
modules in the library package, and act as 
guides to the program listings that are 
available as part of the PL/I Library 
distribution. The appendixes contain 
details of the system macro instructions 
used, 3ystem generation, library 
pseudo- registers and macro instructions, 
library internal error codes and associated 
messages, and PL/I control blocks. 
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CHAPTER 1: THE PL/ 1 LIBRARY 



FUNCTION 



The PL/I library was designed as a set of 
reentrant load modules, each performing a 
single function or a group of related 
functions . 

The library modules can be divided into two 
groups : 

1. Those that act as an interface between 
compiled code and the IBM System/360 
Operating System; these modules are 
mainly concerned with input/output, 
dynamic program and storage 
management, and error and interrupt 
handling. 

2. Those that are closed subroutines 
specifically designed to perform 
arithmetic computations, data 
conversions, I/O editing and string 
generic built-in functions as the 
major part of their task. 



USAGE 



The linkage editor or linkage loader 
combines the object modules from a PL/ I 
program with their required library modules 
to produce executable load modules. This 
is done by means of the external symbol 
dictionary (ESD) which resolves all direct 
references to the library modules by 
entry-point names (seven- character names) 
or, under certain circumstances, by module 
name (containing six characters). (See 
'Naming Conventions' - Chapter 2) 

The library modules may in turn call 
other, secondary, library modules (e.g. as 
in data conversion) . To ensure that only 
the ones required are called, any library 
object module that calls a secondary module 
is preceded by a linkage-editor LIBRARY 
statement. This statement specifies that 
the references to the secondary modules 
(which are seven-character entry-point 
names) should not be resolved unless the 
secondary modules are already part of the 
input to the load module. For any such 
secondary modules called, the compiler 
generates an ESD in which the references 
are six-character module names. 

The PL/I library acts as the sole 
interface between compiled code and the 
operating system. The compiled code does 



not issue SVCs or system macro instructions 
but instead issues a library call. 
Although the library nodule (s) called can 
issue an SVC instruction, it is more 
convenient to use system macro 
instructions. This method means that when 
the operating system changes, only the 
library module is rewritten, with the call 
to the library. from the compiler remaining 
as before. Similarly, if the SVC calling 
sequence changes, the system macro is 
changed accordingly and the library module 
need only be reassembled. 

For further details on macro 
instructions, see IBM System/360 Operating 
System; Supervisor and Data Management 
Macro Instructions . The system macro 
instructions used by the library are listed 
in Appendix A. 

The PL/I library for each version of the 
F compiler is compatible with previous 
versions only. For example, whilst a 
module compiled under Version 2 can be 
link-edited and executed by an operating 
system that includes the Version 3 
compiler, the reverse is not possible. 

User-designed modules can be substituted 
for library modules; each user module is 
given the name of the library module it is 
meant to replace. 



Link Library 



certain modules are loaded dynamically 
during program execution. These modules 
reside in the link library (SYSl.LINKLIB) ; 
they are transient modules and are loaded, 
when required, by the system macros LINK, 
LOAD and XCTL. DD statements are not 
required. The link-library modules are 
marked * in Appendix G; they comprise: 

1. The print and message modules of the 
error and interrupt handling 
subroutines . 

2. The modules for opening and closing 
files . 

3. The record-oriented I/O transmission 
modules. 

4. Special multitasking modules. 

These modules can be replaced by 
user-designed modules, if required. The 
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user module is placed by the linkage editor 
into a partitioned data set (PDS) ; this 
data set must be described in a JOBLIB DD 
statement. 

All library modules normally residing on 
SYS1. LINKLIB may be made resident in the 
system when operating under MFT II or MVT. 

In an MFT II system, the resident area 
is effectively an extension of the nucleus; 
in an MVT system, the resident area is a 
section of the high order main storage 
called the LINK PACK AREA (LPA) . 

Load Library : all other library modules are 
link-edited with compiled code by the 
linkage editor- These modules reside on 
SYS1.PL1LIB, and, normally, they may not be 



resident in the system. However, the new 
shared library feature permits selected 
combinations of modules to be made resident 
by combining them into a load module (for a 
discussion on the shared library feature, 
see Appendix B) . 



INSTRUCTION SET REQUIREMENTS 



The universal instruction set is generally 
required for the execution of PL/I 
programs. It is possible that 
floating-point or decimal instructions may 
be used in the execution of programs that 
do not use floating-point or decimal data. 



I 
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CHAPTER 2; GENERAL IMPLEMENTATION FEATURES 



NAMING CONVENTIONS 



LINKAGE CONVENTIONS 



PL/I library external names always begin 
with IHE; this is followed by two, three or 
four characters, according to the name 
function (see Figure 1) . 



REGISTERS: SYMBOLIC NAMES 



The following symbolic names are used in 
the library modules for aeneral registers 
0-15: 





Symbolic 


Register 


Name 





R0 


1 


Rl,RA 


2 


RB 


3 


RC 


4 


RD 


5 


RE 


6 


RF 


7 


RG 





Symbolic 


Reqister 


Name 


8 


RH 


9 


RI 


10 


RJ 


11 


RX,WR 


12 


PR 


13 


DR 


in 


LR,RY 


15 


BR,RZ 



The following symbolic names are used 
for the floating-point registers: 

Symbolic 
Reqister Name 



FA 
FB 
FC 
FD 



Linkage between modules generally follows 
the operating system standard calling 
sequence. The main features of this are: 



1. Arguments are passed by name, not by 
value. The addresses of the arguments 
are passed, not the arguments 
themselves. 

2. These addresses are stored in a 
parameter list. 

3. The address of the list is stored in 
register RA. 

Full details are provided in IBM System/360 
Operating System: Supervisor and Data 
Management Services . 

Some PL/I Library modules, however, are 
called by a PL/I standard calling sequence. 
The main features of this are: 

1. Arguments are passed by name. 

2. Arguments are passed in general 
registers. 

This standard can only be used where the 
number of arguments is both fixed and less 
than eight. If these conditions are not 
met, the operating system standard is used. 

Two PL/I Library modules, IHESA and 
IHETSA, do not use either of these 
standards. The subroutines in these 
modules pass arguments by value as well as 



I 



IIHEXXX 



6 |IHEXXX 

7 I IHEXXXX 



+ -J identification of function. 



j. 



Use 



r 1 t 

Number of (Format 
Characters | 

5 |IHEXX 



Module name 



j Meaning 
__ I __ 

I 
I 
| XXX are chosen for mnemonic 



PL/I Library defined macros 

Entry-point name (First six characters are module name; 

| | (the seventh identifies the entry point 

I I | within the module. 

I IHEQXXXJ Pseudo- register name |XXX are chosen for mnemonic 

j I (identification of function. (See 

I j (Appendix c.) 

Figure 1. External Names used by the PL/I Library 
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by name, and pass them in parameter lists 
and in general registers. 

In general, whichever standard is used, 
whenever one module links to another a save 
area must be provided for the contents of 
the registers used by the called module. 
The save area procedure is: 

1. The calling module provides a standard 
save area (SSA) for the called module. 
The address of this save area is 
stored in register DR. 

2. If the called module in turn calls 
another module, it provides that 
module with a save area. Register DR 
now contains the address of this new 
save area. The save areas are chained 
together by the chain-back address 
field in the new save area. 

3. on return to the calling module, the 
following will be unchanged; 

Registers RB through LR 

Program mask 

Program interrupt control area 
(PICA) 

while the following may be changed: 

Registers RO, RA, and BR 

Floating-point registers 

Condition code 

The standard save area is a 72-byte area 
in which the contents of all the general 
registers can be saved. The format is 
described in Appendix H. 

The library does not support 
inter-module trace. Therefore: 

1. The chain-forward field in the SSA is 
not set. 

2. Calling sequence and entry-point 
identifiers are not employed. 



CODING CONVENTIONS 

Because all modules within the PL/I Library 
are coded to be reenterable, the following 
coding constraints must be observed: 

1. The modules are read-only. 

2. Workspace (for save areas and 



temporary work areas) is obtained 
within an area dynamically allocated 
at program initialization or by a call 
to the Get VDA (variable data area) 
subroutine in IHESA. (See 'Library 
Workspace* in this chapter and in 
Chapter 4.) 



LIBRARY MACRO INSTRUCTIONS 



Seven macro instructions are available for 
use in the library modules. To obtain 
these macro instructions, use PL/I (F) 
SYMLIB tape 360S-LM512 XT05-00 and IEBUPDTE 
to create a partitioned data set named 
SYS1.PVTMACS. SYSl.PVTMACS should then be 
concatenated with SYS1.MACLIB (the 
partitioned data set containing the 
standard system macro instructions used by 
the operating system). 

Five of the seven macro instructions, 
IHEEVT, IHELIB, IHEZAP, IHEXLV, and IHEZZZ, 
set up symbolic definitions in the program 
listing and the other two, IHESDR and 
IHEPRV, set the current addresses of the 
standard save area and the pseudo- register 
vector (PRV) respectively. The library 
macros are described in Appendix D. 



DATA REPRESENTATION 



Three types of data may exist within a PL/I 
program : 

1. Arithmetic 

2 . String 

3 . Statement- label 

The internal representation and other 
details of these three types are shown in 
Figures 2, 3, and 4. The invocation count 
used in the statement-label data 
representation is described in Chapter U. 

Arithmetic or string data may be 
specified with the PICTURE attribute. A 
PICTURE arithmetic data item is called a 
numeric field and is represented internally 
as a character string. An arithmetic data 
item without a PICTURE attribute is called 
a coded arithmetic data item (CAD) and is 
represented internally in one of three 
System/360 formats: 

Fix ed- po int binary 
Floating-point 
Packed decimal 



12 



j Data Type j 



Implementation 
■t 



Scale | Base | Precision J Internal | Alignment 
j j | format 



Processing 



I 
H 



j Binary j p,q j Fixed- point | 
j j Max p: 31 j binary 



Fixed f -I +- 

| Decimal) p,q (Packed dec- 
j j Max p: 15|imal 
| | (see | 
j | note) j 



REAL data 

p>15: Word j Arithmetic operations are performed 
p£l5: Half- j on p-digit integers: scale factor q 
word j is specified in a DED. (See Appendix 
JH, 'Data Element Descriptor • . ) 
+ 1 

Byte |The p digits occupy FLOOR ( (p + 2)/2) 
j bytes. Arithmetic operations as for 
j fixed binary 



+ + 






I Float j. — 



h— 



| Binary | p | 

j j Max p: 53 j 
I j j Hexadecimal 

~f— ^ float ing- 

| Decima 1 1 p j point 

| j Max p: 16 j 
I I I 



p<21: Word 
p>21: Double-) 

word j The data is normalized in storage 

^ before and after arithmetic operat- 

p<6: Word jions. 
p>6: Double- j 

word | 

COMPLEX data 

p>15: Word |As for real fixed binary. The real 
p£l5: Half- jand imaginary parts occupy adjacent 
word jfullwords or half words* with the 
j real part first. 



j Binary j p,q | Fixed -point 

j jMax p: 31 | binary 

I 



I l_ I 

Byte JAs for real fixed decimal. The real 

jand imaginary parts occupy adjacent 

j fields, with the real part first. 



j Decimal j p,q | Packed dec- 
| j Max p: 15|imal 



| Binary | p | 
j j Max p: 53 j 
I I I 



Float |— 



p<21: Word |As for real float binary. The real 

p>21: Double- j and imaginary parts occupy adjacent 

word jfullwords or double words, depending 

j on the precision, with the real part 

(first. 

p<6: tford JAs for real float decimal. The real 
p>6: Double- j and imaginary parts occupy adjacent 
word jfullwords or doublewords, depending 

| on the precision, with the real part 

j first. 

L -J X J J. A j 

Note; When p is even, the effective precision for all arithmetic operations except div- 
ision is (p + l,q), except when the SIZE condition is being checked. When this 
occurs, the first digit in the high-order byte mu3t be checked to ensure that it 
is zero. 



j j Hexadecimal 

4 -I f loating- 

| Decima lj p j point 
j JMax p: 16 j 



Figure 2. Arithmetic Data Representaton 



k 



7 8 

Invocation Count 



31 



■T" 

I I 

I A- 

Figure 3. 



A (Statement label) j 
j 

Statement-Label Data 
Representation 



COMMUNICATION CONVENTIONS 



The use of library modules in a PL/I 
program requires that: 

1. Working storage be provided for the 
modules. 
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,. 1 + + 4 



T" 

I 

Data typej-- 



Implementation 



| Representation j 



Length 



| Alignment | 



j. + < 



Byte | 
(see note) | 

Byte | 



Bit |1 binary digit | 

jper bit | Maximum length: 32,767. If a VARYING attribute is 

4 i declared, maximum length is declared length. 

Character j 1 character per | regardless of the string value. 
| byte | 

t J , X J. j 

Notes The string occupies CEIL (n/8) bytes. If the string comes within the scope of an 

UNALIGNED attribute, the address of the first bit is provided by a byte address and 
bit offset in an SDV. (See 'string Dope Vector* in Appendix H. ) 

Figure 4. string Data Representation 



I 



Techniques for passing information 
about arguments and program status be 
provided. 



Working storage is obtained as library 
workspac e (LWS) . Appendix H gives the 
format of LWS, which is allocated by the 
library program management modules IHESAP 
and IHETSA. 



Two modes of communication are available 
for passing information: 

Explicit : Uses parameter lists and 
registers. (See 'Linkage 
Conventions * . ) 

Implicit: Uses pseudo^registers or a 
Library communication area . 

Some library modules are interpretive 
(as opposed to declarative), and 
accordingly require that information 
regarding the characteristics of their 
arguments be supplied. Such information is 
made available to the library in the form 
of standardized control blocks. The form 
and content of the compiler-generated 
control blocks in general use throughout 
the implementation are described in 
Appendix H; one or more blocks is required 
according to the nature of the data passed: 

Scalar arguments: 

Data element descriptor (DED) 
String dope vector (SDV) 
Symbol table (SYMTAB) 

Array arguments: 

Array dope vector (ADV) 

String array dope vector (SADV) 

Structures: 

Structure dope vector 

Dope vector descriptor (DVD) 

Formats: 

Format element descriptor (FED) 



Special-purpose control blocks, such as 
the file control block (FCB) , are described 
in Chapters 3, 4, and 5, and in Appendixes 
I, J, and K. 



Ps e udo - Register Ve ctor (PRV) 



This is an area of ta3k- oriented storage, 
addressed through register PR. The PRV 
contains a number of pseudo-registers which 
effectively operate as implicit arguments 
and give information about, for example, 
current program status. All references to 
specific pseudo-registers within the PRV 
are made by the addition of a fixed 
displacement to the PRV base address in 
register PR. 

A pseudo- register is defined within a 
library module as a Q-type address constant 
which is fixed during the linkage editing 
process. All pseudo-register address 
constants within the PL/I implementation 
are two bytes long. The maximum size of a 
PRV is 4096 bytes. The pseudo- registers 
used by the PL/I Library are shown in 
Appendix c. 



Library Workspace (LWS ) 



Various library modules require working 
storage: 

1. For internal functions. 

2. For linkage to other modules. (A 
register save area must be provided. ) 

Since the library is designed to function 
within a multitasking environment, such 
storage must be allocated on a 
task-oriented basis. The storage so 
allocated is termed library workspace 
(LWS). 
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Library modules which use LWS refer to 
it by means of the PRV. A group of 
pseudo-registers in the PRV is set during 
LWS allocation to contain the addresses of 
contiguous areas within LWS. (See Appendix 
H.) Each of these areas is at a different 
level . 



The notion of level exists because of 
inter-module linkage between library 
modules: 

1. A module which invokes no other 
modules is assigned level 0. 



2. A module which invokes other modules 
is assigned a level number greater 
than the level number of any invoked 
module. 

3. A module which transfers control to 
another module (i.e., does not expect 
a return) is assigned the level number 
of that module. 

Invocation of the error-and-interrupt- 
handling subroutine is not considered 
sufficient to raise the level number of the 
invoking module, since the error subroutine 
uses a special level. 

Library workspace is allocated as 
primary or secondary LWS. 

Primary LWS is allocated during program 
initialization, before control is passed to 
the main procedure. The storage thus 
obtained is not freed until the PL/I 
program is finished. 

Secondary LWS is allocated for special 
purposes during program execution and is 
freed when the situation for which it was 
created no longer exists. It is allocated: 

1. When an on- unit is entered from a 
library module. This may lead to a 
recursion problem: library modules 
called may overwrite this LWS. ro 
avoid this, the existing LWS is 
stacked, a new one obtained and all 
the LWS pseudo- registers updated. 

2. When SNAP, system action or error 
messages are to be printed. The PRINT 
subroutine may overwrite the existing 
LWS: to avoid this, the same procedure 
is followed as for an on- unit. 

The library program management module 
IHESAP controls the allocation of LWS and 
the setting of library pseudo-registers. 
(See Chapter 4.) The library macro IHELIB 
controls the length of LWS and of each area 
within it. The LWS format can be changed 
by changing IHELIB and reassembling IHESAP. 



Modules using specific areas in LWS 
address these areas by the following 
library macros: 

IHEPRV: Used to address the LCA or when 
using an area as temporary workspace. 

IHESDR: Used when a module requires a 

standard save area for a module it is 
calling. 



Library Communication Area (LCA) 



Within the area allocated for library 
workspace is an area in which various 
symbolic names are defined. These names 
are used for implicit communication between 
library modules (mainly the data conversion 
modules). This area is the library 
communication area (LCA) ; its format and 
the usage of the symbolic names are shown 
in Appendix H. The LCA address is stored 
in the pseudo-register IHEQLCA. 

In the LCA there is a doubleword 
immediately before the first symbolic name. 
This contains (in the first four bytes) the 
address of the prior generation of LCA 
within a given task. This field is used to 
readdress the LCA which existed before an 
ON block was entered. IHEQLCA contains the 
address of the first symbolic name. 



Object- Time Dump 



A PL/I user may obtain a dump at any time 
by calling one of the following: 

IHEDUMC: Dump current task and then 
continue execution. 

IHEDUMJ: Dump all tasks and then continue 
execution. 

IHEDUMP: Dump all tasks and terminate 

major task (i.e., terminate the 
job step) . 

IHEDUMT: Dump current task and then 
terminate it. 

Identification of required information 
(such as save-area locations) in the dump 
is difficult because this information is 
not necessarily stored in locations 
arranged in a chronological sequence. To 
facilitate reading the dump, therefore, two 
subroutines, IHEZZC and IHEZZP, are 
provided. They extract certain information 
(chiefly about save areas and opened files) 
and print it as an index to the dump. Pull 
details of this information are given in 
Appendix F. 
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If a DD card exists, the information 
will be printed on the PL1DUMP file (unless 
there is something wrong with the PL/I 
save- area chains, in which case the 
SYSABEND or SYSODUMP file will be used) . 
If the data set specified is other than the 
SYSOUT file, DISP=MOD should be used on the 
DD card. If there is no DD card and the 
operating system has the primary control 
program or MPT, only the normal indicative 
dump will be provided; in an MVT 
environment, if there is no DD card, there 
will be no dump at all. 



Checkpoint/Restart 



In an operating system with PCP, MFT II or 
MVT, a PL/I user may establish a checkpoint 
at any point within a job step by calling 
IHECKPS or IHECKPT. If IHECKPT is called, 
he must include a DD statement with the 
ddname SYSCHK to define the data set on 
which the checkpoint information is to be 
saved. If IHECKPS is called, any ddname 
may be used for the same purpose. 



Normally, the automatic restart function 
restarts the program at the most recent 
checkpoint whenever an abnormal termination 
occurs. If, however, a restart is to be 
forced by the user, CALL IHEREST must be 
specified. Alternatively, the automatic 
restart function can be disabled by the 
statement CALL IHERESN. This statement 
disables the automatic restart for any of 
the checkpoints if it is enabled; if it is 
already disabled, then it is considered and 
treated as a NOP. 



Automatic restart can be re-established 
by issuing a call to the checkpoint modules 
IHECKPT and IHECKPS. 

The module IHECKP is called directly 
from compiled code. It obtains an ordinary 
VDA for use as a save area, rather than 
using library workspace, because the CHKPT 
macro instruction that is issued by IHECKP 
makes use of the first byte of the save 
area; the first byte of a save area in LWS 
is used for PL/I information. (Refer to 
Chapter 4 for a discussion of the VDA and 
LWS VDA.) Each time IHECKP is called, it 
creates, from a dummy held as part of the 
module, a DCB that refers to the data set 
defined by the ddname specified as a 
parameter to IHECKPS. As well as the 
address of the DCB, the checkpoint 
identifier specified for IHECKPS is also 
passed to the IHECKPT routine. 



Sort/Merge ■ •* PL/I Interface 



A PL/I procedure may call the operating 
system Sort/Merge program. Using the 
library module IHESRT. The publications in 
which the operation of Sort/Merge is 
described are: IBM System/ 360 Operating 
System; Sort/Merge . Form C 28- 6 543, and, 
Sort/Merge Program Log ic M anual, Form 
Y28-6597. 

Four entry points, IHESRTA, IHESRTB, 
IHESRTC, IHESRTD are provided to enable use 
to be made of Sort/Merge user exits El 5 and 
E35 to call PL/I procedures, as required by 
the application. 

Sort/Merge control statements are 
supplied as arguments to the PL/I CALL 
statement. These arguments correspond in 
format to standard Sort/ Merge control 
statements, from which the parameter lists 
are generated. 

These arguments also specify the PL/I 
entry points to be invoked by the user 
exits El 5 and E35, and any return codes to 
be used for inter-program communication. 

The normal library conventions for 
save-area chaining are not used for this 
module. Instead the module allocates a DSA 
(with code X'SO* in the first byte). This 
is to ensure that if either user exit is 
used, the chain- back is through the DSAs 
only. 

After the parameter list for Sort/Merge 
is generated, the following actions are 
performed before linking to Sort/Merge: 

1. The registers in the external save 
area of the PL/I procedure are saved 
and replaced by special registers 
which are used in terminating the sort 
when: 

a. A PL/I exit procedure is 
terminated, due to an error, before 
the sort has terminated, or 

b. A GO TO from an exit procedure to a 
procedure at a level equal to, ..of 
higher than, the calling procedure, 
occurs. 

Otherwise the PL/I procedure would 
terminate allowing the operating 
system to regain control, either 
directly or indirectly, while the link 
to Sort/Merge is still operative, with 
a resultant system interrupt. The 
registers stored in the special save 
area cause the calling procedure to 
enter IHESRT and complete the 
Sort/Merge operation. Any user exit 
calls to tne now non-existent PL/I 
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exit procedures are deleted, before 
restoring the external save area and 
returning control from the PL/I 
procedure. 

2. The PICA is set to system action for 
program interrupts. 

3. Register 13 is set to a special save 
area with a chain back address of 
zero. 

On normal completion of the sort, the 
PICA and external save area are reset to 



the conditions at entry to IHESRT and 
control is returned to the calling program. 



If an exit is taken, the PL/I 
environment is reestablished and register 
13 is reset to the DSA allocated for 
IHESRT. The exit procedure is then invoked 
and thus the DSA chain is correct. 

Before returning to Sort/Merge the PICA 
and register 13 are reset to their values 
on initial entry to the exit routine in 
IHESRT. 
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CHAPTER 3: INPUT/OUTPUT 



FILES AND DATA SETS 



FILE ADDRESSING TECHNIQUE 



Within this publication, the term 'data 
set* refers to a collection of records that 
exist on an external device. A file is 
known as such only within a program; it is 
possible that, within a given program, 
several files will use the same data set 
concurrently (direct access only) . 
Similarly, a data set may be used by 
several programs, either concurrently or 
successively. 



The relationship between a file and a 
data set is established when the file is 
opened. The data set to be associated with 
a file is identified by the TITLE option. 
If this option is omitted or an implicit 
open occurs, a default identifier is formed 
from the first eight characters of the file 
name. The data set identifier is not the 
data set name, but the ddname (i.e., the 
name of the DD statement) . Error messages 
which are related to file operations use 
the full file name (1 through 31 
characters) . 



The attributes of a file in some 
instances restrict the attributes of its 
associated data set, but in those instances 
where device independence is possible, the 
full capabilities of the job control 
language DD statement are available. Unit 
assignment, space allocation, record format 
and length, and various data management 
options (such as write- verify) are 
established on a dynamic basis. 



In order to accommodate reentrant usage of 
a PL/I module, which may imply that the 
module exists in read-only storage, the 
following technique is employed to 
communicate file arguments. All calls from 
compiled modules to the library involving 
file arguments address a read-only control 
block, the DCLCB. The library, using a 
field within this control block, is able to 
address a cell within the pseudo-register 
vector generated for the task. This cell, 
the file register, in turn addresses a 
dynamically allocated control block, the 
file control block (FCB) . (See Figure 5.) 



Declare Control Block (DCLCB) 



This control block, generated during 
compilation, contains information derived 
from a file declaration (either explicit or 
contextual). In addition, it contains the 
offset within the PRV of the file register, 
a fullword pseudo-register employed within 
the file addressing scheme. This 
pseudo-register contains the address of a 
dynamic storage area containing a file 
control block. The DCLCB is read-only, and 
thus permits compiled programs to exist 
within a reentrant environment (which may 
imply that the program is loaded into 
supervisor protected storage) . The maximum 
length of a DCLCB is 56 bytes. 

File attributes specified within the 
DCLCB may be supplemented, but not 
overridden, by attributes specified in the 
OPEN statement which opens the file. An 



DCLCB 



PRV 



FCB 





| PRV offset | 

h T J 



31 



+ >l 



A (FCB) 



Figure 5. File Addressing Scheme 
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exception to this rule is the LINESIZE 
option, which overrules record length 
information declared in the ENVIRONMENT 
attribute. 



The format of the DCLCB is described 
fully in Appendix I. 



File Control Block (FCB) 



This control block is generated during 
program execution when a file is opened. 
Dynamic allocation of the FCB storage is 
required in order to accommodate reentrant 
usage of a given module, for the FCB is not 
read-only. The FCB contains fields for 
both the PL/I Library and for operating 
system data management. The initial 
portion of an FCB is PL/I-oriented, while 
the second portion is the DCB required by 
data management for all data set 
operations. The PL/I portion, called the 
DCB-appendage, is described in Appendix I; 
details of the various DCB constructions 
are available in the following IBM 
publications : 

IBM System/360 Operating System; System 
Control Blocks 

IBM System/360 Operating System; 
Supervisor and Data Management Services 

IBM System/360 Operating System; 
Supervisor and Data Management Macr o 
Instructions 

IBM System/ 360 Operating System; System 
Programmer's Guide 



An FCB is generated for each file opened 
within a program; an FCB cannot exist for 
an unopened file. FCBs are generated in 
task-oriented storage (in the same subpool 
as the PRV for the task; subpool 1). 

Accordingly, if a file is implicitly 
closed because of the termination of the 
task that opened it, its FCB is freed and 
the file register is set to zero. The 
contents of a given file register in a 
non-opening upward task are zero. 
Subsequent reference to the file may cause 
the file to be reopened. (A non-opening 
upward task for a given file is a task that 
does not open the file, and which is not a 
subtask of a task that has opened the 
file.) 

When a file is opened, its generated FCB 
is placed in a chain which links together 
(through the TFOP field in the FCB) all 
files opened in a given task. When files 
are closed, they are removed from the 
chain. This chain, which is anchored in 
the PRV cell IHEQFOP, exists in order to 
perform special PL/I closing processes at 
task termination (whether normal or 
abnormal). When a task terminates, the 
object-program housekeeping routines 
determine which files are currently opened 
by this task. This is performed by the 
relevant housekeeping module calling 
IHEOCLD (close) , which scans the chain and 
calls IHECLTB to close all files opened in 
the current task. If the cell IHEQFOP is 
zero, then no files are, at present, opened 
by the task. When a subtask is attached, 
this cell is initialized to zero in the 
newly generated PRV. The IHEQFOP chain is 
shown in Figure 6. 

Since an FCB is generated in dynamic 
storage, its address cannot be determined 
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Note; The FCBs are opened in the order 1, 2, 3, etc. 
Figure 6. Format of the IHEQFOP Cha'in 
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either at compile time or link-edit time; 
it is this characteristic of the FCB which 
requires the file addressing scheme 
outlined above. If a given procedure is 
being executed by two or more jobs 
(multi- jobbing), an FCB (with its 
associated PRV) exists for each job; the 
procedure does not, however, necessarily 
operate on different data sets. Similarly, 
if a file is opened in two parallel 
sub tasks, an FCB exists for each task. 



Program Execution 



When program execution is initiated, the 
PRV (including all file registers) is 
initialized to zero. When a file is opened 
(prepared for I/O operations), its 
associated file register is set to address 
an FCB; similarly, when a file is closed 
explicitly, its file register is again set 
to zero. 

Since a copy of the PRV of the attaching 
task (calling procedure) is provided to the 
attached task (called procedure) , the state 
of a file is communicated downward through 
major to minor tasks. If the file is not 
open, the file register remains zero. If a 
file has gone through the opening process 
but has failed to be opened (UNDEFINEDFILE 
condition) , the high-order byte (bits to 
7) of the file register will contain an 
error code that indicates the cause of 
failure. The codes consist of two 
hexadecimal digits; they are shown in 
Figure 7. 

If the file register is non-zero, the 
file is open and its FCB is also available 
to all the subtasks created while the file 
was in the open state. This technique of 
communicating the state of a file makes it 
possible to access a file in two parallel 
subtasks. 

Two advantages of the use of the DCLCB 
in the file addressing scheme are: 

1. Because the DCLCB, in conjunction with 
an implicit opening statement, 
provides all the information necessary 
to open a file, a file can be opened 
by I/O statements other than the OPEN 
statement. 



| Error | 

j code j Meaning 

L J. 


| 81 


Conflict between DECLARE and 
OPEN attributes 


| 82 


File access method not 
supported 


| 83 


No block size 


| 84 


No DD card 


1 85 


TRANSMIT condition while 
initializing data set (only 
applicable to DIRECT OUTPUT 
REGIONAL files) 


| 86 


Conflict between PL/ I 
attributes and environment 
options 


| 87 


Conflict between environment 
options and DD parameters 


| 88 


Key length not specified 


| 89 


Incorrect block size or logical 
record size specified 


| 8A 


Line size greater than 
implementation-defined maximum 



H 



L J. J 

Figure 7. Error Codes Indicating Causes 
of Failure in Open Process 



OPEN/CLOSE FUNCTIONS 



The opening of a file occurs either 
explicitly by the use of an OPEN statement, 
or implicitly because of other I/O 
operation statements. 

Opening a file involves the creation, 
within dynamic storage (subpool 1 of the 
opening task) , of an FCB, the setting of a 
file register to address the FCB, and the 
invocation of the data management OPEN 
executor* The closing of a file involves 
invocation of the data management CLOSE 
executor, freeing FCB storage, and clearing 
the associated file register. 



2. Because the DCLCB is part of the 

static storage of a load module, its 
address is constant throughout program 
execution. This address can be used 
therefore as the file identification 
in ON conditions that relate to files. 
ON conditions may be enabled for a 
file before it is opened, since the 
DCLCB address is always available. 



EXPLICIT OPENING 



In order to conserve storage, the module 
structure of the OPEN and CLOSE processors 
involves a ■bootstrap' routine, IHEOCL, 
which links to the modules IHEOPN and 
IHECLT. In a multitasking environment 
IHEOCT links to IHEOPN and IHECTT. The 
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bootstrap module passes to the loaded 
modules the address of a list of all 
necessary address constants and 
pseudo-register offsets, since these 
cannot be set in a module not 
link-edited with the executing 
program. The list is found in the 
library module IHESAP 
(non-multitasking) or IHETSA 
(multitasking) . 

All errors are communicated back to 
IHEOCL/IHEOCT by means of the file 
registers; IHEOCL/IHEOCT then invokes the 
error handling subroutine. The error 
conditions are signaled in the high-order 
byte of the file register; IHEOCL/IHEOCT, 
upon detecting an error condition, sets bit 
of this register to indicate an 
unopenable file. The error codes are shown 
in Figure 7. 



Open Control Block (OCB) 



One of the parameters which may be passed 
to IHEOPN is the open control block (OCB), 
which is generated by the compiler. This 
four-byte control block indicates the 
attributes specified in the OPEN statement. 
During the opening process, this 
information is merged with that in the 
DCLCB in order to construct the proper PCB 
and check for attribute conflicts. (See 
Appendix I for details of the OCB. ) 



is required in order to allow subsequent 
direct insertion of records into the data 
set. If, in phase I, all files specified 
in the OPEN statement have detected errors, 
a return to the bootstrap IHEOCL is made 
immediately. Otherwise phases II, III and 
IV are invoked and a return is made to 
IHEOCL from IHEOPQ. 



| OCL/OCT | 

| OPEN/CLOSE |< 

| bootstrap j 
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r 1 r 1 

j OPN | | OPZ | 

j. < j. 1 

| OPEN |< >| REGIONAL j 

j Phase I j | Formatting] 
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I 
V 

r t 

| 0P0 | 

| OPEN | 
j Phase II | 
i r j 

I 
V 

I OPP I I OPQ | 

j. < j. j 

I OPEN j- >j OPEN i- 

j Phase III | | Phase IV | 



The Open Process 



The flow through the OPEN modules is 
illustrated in Figure 8. 

The open process is performed by the 
modules IHEOPN, IHEOPO, IHEOPP, IHEOPQ and 
IHEOPZ which reside within the LINKLIB data 
set. These modules are dynamically loaded 
in order to conserve object-program 
storage. They initially receive control 
from a bootstrap module, IHEOCL 
(non-multitasking) or IHEOCT 
(multitasking) ; each module, after 
performing its functions for all files 
being opened, passes control to the next by 
the XCTL macro. IHEOPQ then returns to the 
bootstrap module. 

Open Process, Phase I; IHEOPN; This 
performs file attribute checking and 
defaulting functions. If a file being 
opened is REGIONAL, and is opened for 
DIRECT OUTPUT (creation), the module IHEOPZ 
is invoked by IHEOPN to initialize (format) 
the initial space allocation of the 
associated data set. Such initialization 



Figure 8. Flow through the OPEN Modules 

Initialization for REGIONAL data sets of 
F format records involves writing dummy 
records (and keys, except for REGIONAL (1)) 
throughout the data set. On the other 
hand, initialization for U or V format 
records (REGIONAL (3) only) requires merely 
that the capacity record (RO) be written in 
each track to signal a free track, the 
track being automatically cleared as well. 

Open Process, Phase II: IHEOPO: This 
obtains storage for an FCB for each file 
being opened, and sets fields in both the 
DCB and the DCB-appendage according to the 
declared attributes. 

Open Process, Phase III: IHEOPP: This 
executes the OPEN macro, and accepts 
DCB-exits. 

Open Process, Phase IV: IHEOPQ: This 
dynamically loads record-oriented I/O 
modules (setting their addresses in the 
FCB) , and enters the files being opened 
into the IHEQFOP chain of files opened in 
the current task. 
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The Close Process 



Record- oriented I/O: 



This process consists of: removing files 
from the IHEQFOP chain; freeing dynamically 
acquired storage (file control blocks, 
buffers, exclusive control blocks, and I/O 
control blocks) ; and deleting any 
appropriate dynamically- loaded 
record-oriented I/O modules. In the 
following description the non-multitasking 
module is followed with its multitasking 
alternative in parentheses. 

Module IHEOCL (IHEOCT) starts the close 
process; for an explicit close it links to 
IHECLTA (IHECTTA); for an implicit close to 
IHECLTB ( IHECTTB) . If the last operation 
on a BUFFERED SEQUENTIAL INDEXED OUTPUT 
embedded-key file, before it is closed 
explicitly, is LOCATE, module IHEOCL 
(IHEOCT) replaces the embedded key with the 
KEYFROM option, before passing control to 
IHECLT (IHECTT). For further information 
refer to Indexed Data Sets on page 35. 

Module IHEOCL (IHEOCT) calls IHEITC to 
finish formatting the current extent when 
closing a REGIONAL SEQUENTIAL OUTPUT file. 
If IHEITC finds a key sequence error due to 
a previous LOCATE statement on a REGIONAL 
file with U- or V-format records the key 
sequence is ignored and a message is 
displayed on the console. 

The normal return from a KEY on-unit is 
to the statement following that in which 
the condition is raised. Consequently, if 
the KEY condition is raised during the 
execution of an explicit CLOSE statement, 
the file will not be closed unless the 
on-unit also includes a CLOSE statement. 

In addition, if a file is closed 
implicitly (on termination of a task), 
IHEOCL or IHEOCT scans the IHEQFOP chain to 
find the file. In a multitasking 
environment, if a task is terminated 
normally, IHEOCT unlocks all records locked 
in the task and frees the corresponding 
exclusive blocks; if a task is terminated 
abnormally, it merely removes the exclusive 
blocks from their chains. For an implicit 
close, all events associated with event 
variables in the IHEQEVT chain are purged, 
and the associated IOCBs, if any, are 
freed. 

Modules IHECLT and IHECTT reside within 
the LINKLIB data set and are loaded 
dynamically in the same manner as the OPEN 
modules. They perform additional special 
functions as follows: 

Stream-oriented I/O: 

If OUTPUT with U-format records, the 
last record is written. 



All incomplete event variables 
associated with the file are set 
complete, abnormal, and inactive, and 
the I/O operations are purged. 

In a multitasking environment: 

1. The event variables in the TEVT 
chain are set complete, abnormal, 
and inactive. 

2. For a REGIONAL EXCLUSIVE file, or 
an INDEXED EXCLUSIVE file with 
unblocked records, locked records 
are unlocked and all exclusive 
blocks in the TXLV chain are freed. 

3. For an INDEXED EXCLUSIVE file with 
blocked records, the file is 
unlocked. 



IMPLICIT OPENING 



If a file is not open and an I/O operation 
is initiated, then one of the compiler- 
interface modules (IHEIOA, IHEIOB (or 
IHEIBT), or IHEION (or IHEINT)) calls 
IHEOCL (or IHEOCT) , at implicit-open entry 
point IHEOCLC (or IHEOCTC) , passing any 
implied parameters, and the open process 
begins. 

If the OPEN modules return control to 
IHEOCL (or IHEOCT) and the file is still 
unopened, the UNDEFINEDFILE condition is 
raised. 



STREAM-ORIENTED I/O 



Although I/O devices available within IBM 
System/360 are usually designed to transmit 
data in records of various lengths 
(blocks), the stream-oriented facilities 
allow a program to ignore record 
boundaries. The GET and PUT statements 
transmit data between storage and one or 
more record areas which exist within a 
buffer, the location within the buffer 
being updated as each data field is 
accessed. When a record area becomes 
filled (if output) or empty (if input), 
another record is obtained. Support for 
record access is provided by the data 
management access method QSAM (queued 
sequential access method). Normally, the 
GET and PUT data management macros are used 
in the locate mode, to conserve space and 
time; paper tape input, however, must use 
the MOVE mode. See Figure 9 for the flow 
through the stream-oriented I/O modules. 
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• Figure 9. Modular Linkage through Stream-Oriented I/O 



Chapter 3: Input/Output 23 



CURRENT FILE 



STANDARD FILES 



The current file is that one which is being 
operated upon by an I/O statement; it is 
established when an operation begins, and 
removed when the operation is completed. 
The current file is addressed through the 
pseudo-register IHEQCFL, which addresses 
the DCLCB for the file. This 
pseudo-register is available for inspection 
upon entry to ON blocks, and during 
transmission. Its format is shown in 
Figure 10. 
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A (DCLCB) 
A (Abnormal return) 



Figure 10. 



Format of the Current File 
Pseudo-Register 



Within a stream-oriented data 
specification there may exist expressions 
which involve function references. In 
turn, the function procedure may itself 
perform I/O operations or may refer to ON 
blocks that perform I/O operations. When 
this situation occurs, it is necessary to 
stack the current file pseudo- register. 
The presence of the COPY option in a GET 
statement and the raising of the TRANSMIT 
condition for an item in the data stream 
are flagged in the fifth byte of IHEQCFL: 



TRANSMIT to be raised on item : Bit 5=1 

COPY option in statement: Bit 6=1 

Current file in PRV: Bit 7=0 

Current file stacked in DSA: Bit 7=1 



Stacking of the current file is effected 
by the I/O initialization modules; upon 
entering such a module (e.g., IHEIOA and 
IHEIOB), the contents of the 
pseudo-register IHEQCFL are stored in the 
DSA (dynamic storage area) of the invoking 
procedure, as addressed by register DR. 
The stacking cell is termed the current 
file pseudo- register update. (See Chapter 
4.) Upon termination of an I/O operation, 
either normally, or by means of a GO TO 
statement out of an ON block, this cell is 
copied back into the pseudo- register 
IHEQCFL. 



GET and PUT statements with the STRING 
option employ the current file 
pseudo-register, but no abnormal return 
entry exists. Instead, the latter four 
bytes address a simulated FCB. 



The standard files, SYSIN and SYSPRINT, 
have default titles equivalent to their 
file names. The compilation of GET and PUT 
statements without explicit FILE options 
causes compile-time syntax substitution of 
the file names SYSIN and SYSPRINT 
respectively. These files have the same 
compiled linkage to the library as other 
files. Within the library, SYSIN is not 
used; the file SYSPRINT, however, is used 
in that error messages and listing of data 
fields for the COPY and CHECK options 
require the presence of this file. 



I by: 



1. 



2. 



SYSPRINT may be implicitly opened either 



the first PUT executed in the compiled 
procedure, or 

a call from within the library for the 
COPY option or an error message. 



If the library attempts to open this file, 
and it cannot be opened (missing DD card, 
etc.), this situation is flagged and all 
error messages will appear on the system 
console. In addition, any COPY options, or 
system action for the CHECK condition, will 
be ignored. The UNDEFINEDFILE condition is 
suppressed in the above cases. 

If a compiled procedure attempts to open 
SYSPRINT, and it cannot be opened, the 
normal UNDEFINEDFILE condition is raised. 

Because the library and the source 
program both use the SYSPRINT file, it is 
necessary that they both refer to the same 
DCLCB. This is achieved by the use of 
CSECT facilities within the linkage editor; 
both the compiled DCLCB and the 
library-supplied DCLCB for SYSPRINT (within 
the module IHEPRT) are supplied with the 
same name, so that only one of them will be 
placed within the linked program. The name 
of both CSECTs is IHESPRT; the name of the 
associated file register is IHEQSPR. 



SYSPRINT IN MULTITASKING 



In a multitasking environment, to ensure 
that there is no conflict between 
operations in different tasks that refer to 
the same non-exclusive file, it is 
necessary for the programmer to synchronize 
these operations (by using an EVENT 
variable, the COMPLETION pseudo-variable, 
and the WAIT statement) . Since the library 
uses the file SYSPRINT, it is not possible 
for the programmer to synchronize all 
operations on this file. Therefore the 



2U 



library module that implements PUT 
statements for SYSPRINT (IHEIOB), and other 
modules that use this file, issue an ENQ 
macro instruction before executing each PUT 
statement on SYSPRINT, and a DEQ macro 
instruction on completion of the operation. 
All SYSPRINT operations cannot be enqueued 
on the same resource, since this could 
result in an interlock situation (two or 
more operations, each waiting for the 
completion of the others). For example, 
this would be the case if a PUT statement 
involved a function reference that required 
another PUT operation; if both were 
enqueued on the same resource, the second 
operation could not commence until the 
completion of the first, which itself could 
not proceed until the function had returned 
an answer. 



The library resolves the difficulty by 
employing a resource counter (the first 
byte of the current- file field in the DSA: 
see Appendix J) . Before each SYSPRINT 
operation is executed, the operation is 
enqueued on the resource number in the 
counter, and the counter is then 
incremented by one; on completion of the 
operation, the counter is decremented by 
one before the operation is dequeued. When 
a new DSA is obtained (on entry to a new 
block: see Chapter 4), the resource count 
is copied from the DSA of the block from 
which the new block was entered. 



of an error in a PUT statement in a 
function reference made during the 
execution of the second PUT statement in 
the task. The PUT statement is enqueued on 
resource 0, and the resource count is then 
incremented. When the function is called, 
the resource count (1) is copied into its 
DSA; consequently, the next PUT statement 
is enqueued on resource 1, and the counter 
is again incremented. The count 2 is 
copied into the on- unit DSA when control 
passes to the on-unit. On execution of the 
GO TO statement, which passes control back 
to a statement preceding the original PUT 
statement, IHETSAG frees the function and 
on-unit DSAs, dequeues all the PUT 
operations, and resets the resource counter 
in the DSA for task C to its value on entry 
to the task (0) . 

No special provision is made for 
handling SYSPRINT resources on termination 
of a task, since this file cannot be used 
by the library end-of-task exit routine. 

The qname and rname used in the ENQ and 
DEQ macro instructions are: 

qname (two words) : 

Bytes 1-4: A( SYSPRINT FCB) 
Bytes 5-8: A (SYSPRINT FCB) 

rname (1 byte) : 

Resource count in DSA 



In the example (Figure 11), when the 
major task (task A) is initialized, the 
resource count in its DSA is set to zero. 
Task A then attaches tasks B and C, and in 
each case the resource count (0) is copied 
into the new DSA. Tasks A, B, and c then 
request PUT operations, all of which are 
enqueued on resource 0; in each case the 
resource count is then incremented by 1. 
These operations are therefore completed in 
the order in which they were requested. 

During execution of the PUT statement in 
task B, an error condition occurs that 
involves a library call to print a message 
(e.g., UNDERFLOW). The library PUT 
statement is enqueued on resource 1, since 
the resource counter is incremented after 
the task PUT statement is enqueued, but 
before the statement is executed. The 
library PUT operation is therefore not 
dependent on the completion of the PUT 
statement that raised the error condition. 

If a GO TO statement is executed that 
passes control to a statement preceding a 
series of enqueued operations, the program 
management routine IHETSAG releases the 
DSAs of the blocks thus freed and dequeues 
the I/O operations they contain. This is 
illustrated in task C (Figure 11), where 
control is passed to an on-unit as a result 



GET/PUT OBJECT PROGRAM STRUCTURE 



The code compiled for stream-oriented I/O 
GET and PUT statements has the general 
structure illustrated in Figure 12. There 
are three 'call sets* compiled for these 
statements : 

1. Initialization: 

This call invokes one of the I/O 
initiator modules, passing: 

a. The address of the file DCLCB. 

b. The address of the termination 
call. (This is the abnormal 
return which is set within the 
current file pseudo-register 
IHEQCFL. ) 

c. The address of the LINE or SKIP 
value. 

The initialization process includes 
stacking the current file, checking 
the specified file (and opening it if 
not already open) , and performing any 
necessary option operations. 
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Figure 11. Allocation of SYSPRINT Resources in Multitasking 



2. Data specification: 



3. Termination: 



This is a series of calls to perform 
list-, data-, or edit-directed 
stream-oriented I/O operations. This 
series is omitted only for GET/PUT 
statements which have no data 
specification. Details of the 
implementation of the three forms of 
data specification appear in •Data 
Specifications', below. 



This call invokes the terminal 
subroutine of the module which 
performed the initialization. At this 
point the current file is unstacked 
and (for PUT calls) V format output 
records have their record- length field 
updated. 
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Figure 12. Object Program Structure of 
GET/POT 



DATA SPECIFICATIONS 

There are three forms of data 
specification: 

Data- directed 

Li st- directed 

Edit- directed 

Compilation of any data specification 
yields a series of one or more calls to the 
library for transmission of data between 
program storage and a record buffer. For 
list- and data-directed I/O, the data items 
transmitted are passed by means of the 
standard linkage described above. (See 
• Linkage conventions ' in Chapter 2 . ) The 
PL/I standard (using registers) is employed 
wherever possible; where it is not, the 
operating system standard (using a 
parameter list) is employed. For 
edit-directed I/O, the " executable format 
scheme* described below is required. 

The ON CHECK facilities for data items 
being input are supported by compiled code 
between data- list item specifications, in 



EXECUTABLE FORMAT SCHEME 



The executable format scheme exists to 
support two requirements for edit-directed 
data items : 

1. The matching at object time of 
data- list items with format- list 
items . 

2. The evaluation of expressions during 
an I/O operation. 

The scheme exists in compiled code for use 
by the library format directors and 
conversion package. (See 'I/O Editing and 
Data Conversion* in Chapter 8.) 

The scheme is required because 
edit-directed data specifications contain 
format lists composed of format items that 
may have expressions for replication 
factors and format subfields. These 
expressions may have to be evaluated with 
values read in during a GET operation. 
Finally, the use of dynamic replication 
factors and the possible existence of array 
data-list items of variable bounds prevent 
any pre-determinable matching of data-list 
items and format-list items. 

Basically, the scheme calls for the 
existence of two location counters, one for 
a compiled series of data-list item 
requests, the other for a compiled series 
of format-list item specifications. These 
two series are compiled as the secondary 
calling set for a GET or a PUT operation. 

To support the dynamic matching of a 
format-list item with any data-list item, a 
group of format directors exists within the 
library; one of these directors receives 
the call from the secondary compiled series 
of format item specifications. A director 
will determine which conversions are 
required to satisfy the transmission of a 
data item according to its internal 
representation (described by its DED) and 
its specified external representation 
(described by a FED). 

The structure of edit-directed compiled 
code is illustrated in Figure 13. The 
first column, 'Primary code*, consists of 
calls to units in the second column, 
•Secondary code*; i.e., data-list items are 
requesting a match with a format-list item. 
The third column shows the flow within the 
library as set up by format directors. 
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The scheme works as follows: 

1. The address of the start of the 

format-list code (executable format) 
is obtained. 



2. Transmission of the first data item is 
requested; its storage address and DED 
address are loaded into registers RA 
and RB. 



3. Control is transferred to the 

executable format; at the same time 
the location counter of the data- list 
code is updated. 

H. The executable format loads, into 
register RC, the address of an FED. 

5. A call is made to a format director 
and at the same time the location 
counter of the format-list code is 
updated. 



6. The format director causes the 
conversion package to convert the data 
according to DED and FED information, 
storing the converted data in the 
specified storage address, if input, 
or placing it in a buffer, if output. 

7. Return is then made to the data-list 
code, by means of the data- list 
location counter, LR. 

8. The above steps, 2 through 7, are 
repeated until the end of the 
data- list code is reached. 

Within both primary and secondary code, 
looping and invocation of function 
procedures may occur. Within secondary 
code, the appearance of control format 
items (PAGE, SKIP, LINE, COLUMN, X) will 
cause the location counter for primary 
code, register LR, to be temporarily 
altered, so that control is returned from 
the library, not to the primary code, but 
to the secondary code. This allows the 
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data-list item which activated the control 
format item to be matched with a data 
format item. 



OPTIONS 



COPY: This option causes each data field 
accessed during a GET operation to be 
listed on the standard output file, 
SYSPRINT. This is performed by calling 
the module IHEPRT. Each data field 
occupies the initial portion of a line. 
If there is no DD card for SYSPRINT, 
the COPY is ignored by IHEPRT. 

STRING: This option causes a character 
string to be used instead of a record 
from a file. This situation is made 
transparent to the normal operation of 
the I/O modules since the 
initialization module for GET/PUT 
STRING (IHEIOC) constructs a temporary 
FCB for the string. Information 
regarding the address and length of the 
string is set in the FCB fields TCBA, 
TREM and TMAX. A temporary file 
register is created in the second word 
of the pseudo-register IHEQCFL. (A 
dummy DCLCB is placed in front of the 
generated FCB and consists of two bytes 
which indicate the offset of the dummy 
file register. ) 

PAGE, SKIP, LINE (print files) : These 

options cause the current record (which 
is eguivalent to a 'line') to be put 
out, and a new record area to be 
obtained. SKIP can also be used with 
input to cause the rest of a record in 
the input stream to be ignored. Record 
handling for these functions is 
performed by the module IHEIOP. All 
printing options (and format items) are 
supported by use of the ASA control 
characters : 



Output files : The SKlP(n) option 
causes the remainder of the 
current line (record) to be 
ignored and (n - 1) blank lines to 
be inserted into the output 
stream. Note that, for format F 
records, each line is padded with 
blanks; for format V and U 
records, only the necessary 
control bytes and record lengths 
are supplied. 



RECORD- ORI ENTED I/O 



OBJECT PROGRAM STRUCTURE 



In record-oriented I/O, the data entities 
accessible to the source program are data 
management logical records (unlike 
stream-oriented I/O, where the data 
entities are data fields). 

A wider range of record access is 
therefore available with record-oriented 
I/O: records may be keyed or not, may be 
directly or sequentially accessed, and may 
be manipulated within the data set by 
insertion, replacement, or deletion. The 
specific facilities available vary 
according to the data management access 
method employed to support a given data 
set. 

The data management facilities employed 
are indicated in Figure 14, according to 
the organization of the data set. Note 
that not only the declared organization but 
also the mode of access and the format of 
records determine the chosen access method. 
Details of the manner in which the access 
methods are employed are provided in 
• Access Method Interfaces * . 



1 Page eject 

+ Suppress space before printing 
b Single space before printing 
Double space before printing 
Triple space before printing 

Should spacing greater than triple be 
required for a LINE or SKIP request, a 
series of blank triple space records is 
generated, followed by a single or 
double space record, if necessary. 

SKIP (non-print files) : 

1. Input files : The SKIP(n) option 
causes the rest of the current 
line (record) to be ignored in the 
input stream, and a further 
(n - 1) lines to be ignored. 



General Logic and Flow 



The overall flow of record-oriented I/O 
modules is illustrated in Figure 15. 
Modules IHEION(IHEIOG) (non-multitasking) 
or IHEINT(IHEIGT) (multitasking) are 
general interface modules, one of which is 
invoked by a compiled call for any 
record-oriented I/O statement, in either a 
non-multitasking or multitasking 
environment. This module interprets the 
requested I/O operation, verifies its 
applicability to the specified file (and, 
possibly, implicitly opens it) , and then 
invokes an access method interface module 
(characterized by the module names IHEIT*) 
to have the operation performed. 
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Note 1: FB is not allowed for UNBUFFERED files 



Note 2 : OUTPUT causes data set to be formatted using BSAM (BDAM load-mode) at open time 



Note 3: QSAM is used for REGIONAL (1) BUFFERED but not KEYED 



• Figure 14. Data Management Access Methods for Record-Oriented I/O 



Modules IHEION and IHEINT supersede 
modules IHEIOG and IHEIGT at Release 17. 
The latter are. retained in case a 
previously compiled load module is 
link-edited with the new library. The new 
modules perform the same function as the 
old except that they transfer control to 
the transmitters rather than link to them. 
The transmitters return direct to compiled 
code. This avoids saving and restoring 
registers between the interface module and 
the transmitter. 

The verification of a statement is 
performed by IHEION (IHEINT in 
multitasking) by ANDing together a mask at 
offset -8 from the FCB and the second word 
of the Request Control Block. If the 
result is zero then the statement is 
invalid. The mask in the FCB is set up by 
IHEOPQ to indicate which statements are 
valid, and the RCB contains the statement 
type as a single bit in its second word. 

On receiving control, the interface 
module first performs any necessary key 



analysis and record-variable length 
checking, and establishes any control 
blocks required. It then invokes data 
management for the transmission of a 
record. After transmission, or (if the 
EVENT option is employed) after initiation 
of transmission, control returns to the 
general interface module IHEION (or 
IHEINT) , and thence to the compiled 
program. Errors may be detected within 
IHEION (or IHEINT) before an interface 
module is invoked, or within an interface 
module either before or after data 
management has been invoked. The relevant 
ON condition is raised when detected. 



As indicated by the overall flow 
diagram, record-oriented I/O is implemented 
in such a fashion that the addition of 
further access method interface modules 
requires minimal changes (if any) within 
other parts of the implementation. The 
general interface module IHEION or IHEINT 
provides each access method interface 
module with a standard parameter set: 
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Note; An asterisk indicates that 
the module can be entered 
directly from compiled code 
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•Figure 15. Linkage of Access Modules in Record- Oriented I/O 



RA: A(Compiled parameter list) 

Parameter list: 
A (DCLCB) 

A (Record dope vector /I GNORE/SDV) 
A(Event variable )/0/A( Error return) 
A (KEY | KEYFROM | KEYTO SDV) /0 
A (Request control block) 



The record dope vector and the request 
control block are described below under 
•Record-Oriented I/O Control Blocks'. 



The interface modules are also invoked 
to handle WAIT statements associated with 
I/O events. The WAIT module, having 
determined that an event variable (see 
Appendix I) is associated with a 
record- oriented I/O operation, invokes the 
relevant I/O transmitter (IHEIT*), passing 
the following parameters: 
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RA: A (Compiled parameter list) 
Parameter list: 

A(DCLCB) 

AdOCB being waited for) 

A (Event variable) 

(Reserved) 

A (Request control block) 

The transmitter then completes the 
previously initialized record transmission, 
and performs any checking required before 
returning control to the WAIT module. (See 
also 'The WAIT Statement* in 'PL/I Object 
Program Management in Multitasking'.) 

From the arguments, the interface module 
is able to determine fully the operation 
requested of it. The location of the 
required interface module is available to 
IHEION from the FCB associated with the 
file; the field TACM in the FCB is set 
during the open process to point to the 
appropriate dynamically loaded module. 

Thus, when extra interface modules are 
provided, the only change required in the 
open modules is the provision of code to 
set TACM and any other FCB fields relevant 
to the new access method interface. 



the input or output of varying strings is 
requested. The string dope vector is an 
eight-byte block: 



Bytes 0-3: A (INTO/FROM string) 

Bytes 4-5: Maximum length of string 

Bytes 6-7: Current length of string 
(output), undefined 
(input) 



Request Control Block 



This eight-byte block contains the request 
codes, in the first four bytes, for various 
RECORD I/O operations and options. The 
format is defined in the BREQ field of the 
I/O control block (IOCB). (See Appendix 
I.) 



The additional four bytes which are 
contained in the compiler argument list are 
not copied into the IOCB. Each type of 
Record-oriented I/O statement is 
represented by one bit as follows: 



RECORD-ORIENTED I/O CONTROL BLOCKS 



Record Dope Vector (RDV) 



The record dope vector is an eight-byte 
block that describes the record variable. 
Its format depends on the type of statement 
and the associated options: 



Bytes 0-3: 



A (INTO/FROM area), or 

A (POINTER variable) for SET 

option in READ statement, 

or 
A (buffer) for LOCATE 

statement 



Byte 4: Reserved 

Bytes 5-7: Length of variable 



String Dope Vector (SDV) 



The address of the string dope vector is 
passed instead of that of the record dope 
vector to record I/O interface modules when 



Bit number 


Statement ♦ options 





READ SET 


1 


READ SET KEYTO 


2 


READ SET KEY 


3 


READ INTO 


U 


READ INTO KEYTO 


5 


READ INTO KEY 


6 


READ INTO KEY NOLOCK 


7 


READ IGNORE 


8 


READ INTO EVENT 


9 


READ INTO KEYTO EVENT 


10 


READ INTO KEY EVENT 


11 


READ INTO KEY NOLOCK EVENT 


12 


READ IGNORE EVENT 


13 


WRITE FROM 


14 


WRITE FROM KEYFROM 


15 


WRITE FROM EVENT 


16 


WRITE FROM KEYFROM EVENT 


17 


REWRITE 


18 


REWRITE FROM 


19 


REWRITE FROM KEY 


20 


REWRITE FROM EVENT 


21 


REWRITE FROM KEY EVENT 


22 


LOCATE SET 


23 


LOCATE SET KEYFROM 


24 


DELETE 


25 


DELETE KEY 


26 


DELETE EVENT 


27 


DELETE KEY EVENT 


28 


UNLOCK KEY 


29-31 


Reserved 
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I/O control Block (IOCB) 



Record-oriented I/O employs several data 
management access methods that require that 
operation requests be provided with a 
special form of parameter list. This 
parameter list is termed the data event 
control block (DECB) . A DECB must be 
provided for each operation, but may be 
reused when the operation is completed, if 
several operations are outstanding (owing 
to the use of the EVENT option in I/O 
statements, or multitasking), then one DECB 
is required for each operation. 

In order to meet these requirements, the 
PL/I open process allocates one or more I/O 
control blocks (IOCB), which are 
subsequently manipulated or increased in 
number as follows: 

DIRECT access (BISAM and BDAM) : 
The IOCBs are created by 
IHEITE(BISAM) or IHEITF(BDAM) ; for 
multitasking, they are created by 
IHEITH(BISAM) or IHEITJ(BDAM) . 
Only one IOCB is created at open 
time; any others required are 
created when needed. 

SEQUENTIAL access (BSAM only) : 

All the required IOCBs are obtained 
at open time; an attempt to use 
more than those already in 
existence raises the ERROR 
condition. 

The IOCB format for both these usages is 
described in Appendix I. 

A number of IOCB fields exist in order 
to support the EVENT option. Since the 
operation is split into two parts — 
initiation through the READ, WRITE, etc., 
statements t and completion by the WAIT 
statement — information regarding a 
particular operation must be retained for 
use at the time of completion. For 
example, if a hidden buffer is employed for 
a READ, the address of the user's record 
variable must be retained for subsequent 
movement from the buffer to the specified 
area. 

IOCB — SEQUENTIAL Usage t Manipulation of 
IOCBs for SEQUENTIAL usage is required only 
for BSAM, which is employed for: 

1. CONSECUTIVE UNBUFFERED files. 

2. SEQUENTIAL creation or access of 
REGIONAL files which have the KEYED 
attribute or are unbuffered. 

A number of IOCBs is allocated during the 
open process by means of the GETPOOL macro; 
subsequent selection of a particular IOCB 



is made by a routine similar to that 
provided by the GETBUF macro. Whenever an 
IOCB is selected, it is entered into the 
chain of IOCBs currently in use; the TLAB 
field in the FCB points to the last IOCB to 
be used. 



The chain of IOCBs is required for two 
reasons : 

1. All I/O operations must be checked in 
the order in which they were issued. 

2. Detection of dummy records for a 
REGIONAL (2) or (3) data set requires 
reordering of outstanding requests 
(due to the use of the EVENT option) . 



This chain, however, is principally 
required for the EVENT option, which can 
cause more than one I/O operation to be 
outstanding at a given time. 



The number of IOCBs (buffers) allocated 
is determined by the DD statement 
subparameter NCP. The value of this 
subparameter should not be greater than 1 
unless the EVENT option is employed; if 
NCP =1, there is then one IOCB and one 
channel program. If NCP is unspecified a 
default of i is used. 

The size of each IOCB varies, depending 
upon the organization, the record format of 
the data set, and whether or not the file 
(if REGIONAL) has the KEYED attribute. 
Figure 66 in Appendix I specifies the size 
requirements . 



IOCB — DIRECT^Usagej Manipulation of 
IOCBs for DIRECT~usage is required for botn 
BDAM and BISAM. One IOCB is allocated to a 
DIRECT file when it is opened; subsequent 
selection of an IOCB is performed by the 
modules IHEITE, IHEITF, IHEITH, and IHEITJ. 
Unlike SEQUENTIAL access, the order of I/O 
operation is not normally considered. 
(However, see the BISAM interface modules 
IHEITE and IHEITH.) 

The chain of IOCBs for a given file is 
anchored in the TLAB field in the FCB; the 
chain may be extended beyond the original 
single IOCB if the EVENT option or 
multitasking is used. An extension occurs 
if, while there exists an I/O operation 
that has not been completed, another I/O 
operation is initiated. 

IOCBs for DIRECT access are obtained in 
subpool zero, in order to cope with 
multitask manipulation of the chain. The 
chain of one or more IOCBs is released when 
the file is closed. 
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Exclusive Block 



When a DIRECT UPDATE file is opened in a 
multitasking environment, the interface 
module IHEITH (BISAM) or IHEITJ (BDAM) is 
loaded instead of IHEITE or IHEITF. IHEITH 
and IHEITJ contain code to implement the 
EXCLUSIVE attribute. When a record is 
locked, an exclusive block is created in 
subpool 1 of the current task; the block is 
freed when the record is unlocked. The 
exclusive block contains the qname (address 
of the FCB for the file) and rname (region 
number for REGIONAL (1), region number and 
key for REGIONAL (2) and (3), and key for 
INDEXED) required by the ENQ and DEQ macro 
instructions that are issued to lock and 
unlock the record. The format of the 
exclusive block is given in Appendix I. 



ACCESS METHOD INTERFACES 



This section describes how the PL/I Library 
relates to the various data management 
access methods for record-oriented I/O, and 
gives details of the support required from 
the library for various PL/I features. 
This information supplements, but does not 
replace, that provided in the module 
summaries and in the module listing 
prefaces. 



CONSECUTIVE Data Sets 



The access methods employed for this 
organization are QSAM and BSAM. The choice 
between them is governed by the file 
attributes BUFFERED and UNBUFFERED: 

BUFFERED: QSAM (All record formats) 
UNBUFFERED: BSAM (F,V,U) (Blocked 
records are illegal) 

QSAM (IHEITG): A BUFFERED file is 
specified in order to take advantage of 
automatic transmission, process- time 
overlap, and blocking or deblocking of 
records. All record formats may be 
handled. 

The locate mode of the GET and PUT 
macros is employed with this access method 
(except for paper tape devices) for the 
following purposes: 

1. To support the SET option in READ and 
LOCATE statements, and to support the 
REWRITE statement without the FROM 
option. Module IHEITG allocates the 
data management buffers for the 
records, and sets the pointer 



2. 



appropriately. The first byte of a 
buffer is always on a doubleword 
boundary; for blocked records, the 
user must ensure that his alignment 
requirements are met by adjusting the 
lengths of the variables being 
transmitted. 

To remove or add V- format control 
bytes if the INTO or FROM option is 
employed. 



Paper tape input requires the use of the 
move mode to effect translation of the 
characters transmitted. The open process 
establishes a work area, placing its 
address in TREC; the GET macro instruction 
specifies this area as the receiving area. 
If an illegal character is read from the 
paper tape, the access method (QSAM) passes 
control to the SYNAD routine in IHEITG; 
control returns from the SYNAD routine to 
QSAM. When the GET macro instruction has 
been satisfied, the data is moved into the 
record variable or a pointer is set, and 
the TRANSMIT condition is raised. 

Closing a data set being created by QSAM 
may cause output records to be written by 
the close executor. If an error occurs 
during the closing process, the operating 
system uses the ABEND macro to end the 
task. 

QSAM Sp anned Records ( IH EITK, IHEITL) : 
Buffered VS- or VBS-format records are 
processed using QSAM Locate Mode for input 
(module IHEITK) and QSAM Data Mode for 
output (module IHEITL) . 

The methods employed are similar to 
those described above for module IHEITG 
although the following should be noted: 

1. Update Mode (REWRITE) is not supported 
by the library, since it is not 
possible to update complete records 
(0/S restriction) . 

2. The use of LOCATE or READ SET 
statements will cause a work area to 
be established equal to the maximum 
record size. This area is only 
released if there is a subsequent READ 
(without SET) or WRITE statement. 

BSAM (IHEITB): An UNBUFFERED file is 
specified in order to avoid the space and 
time overheads of intermediate buffers when 
transmitting records. Overlap of 
transmission and processing time is only 
available if the EVENT option is employed. 

BSAM requires the use of DECBs to 
communicate information regarding each I/O 
operation requested of it; see *I/0 Control 
Block (IOCB)' and Appendix I (IOCB) for 
details of the DECB. IHEITB selects an 
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IOCB (which contains a DECB area) from the 
IOCB (buffer) pool for each input/output 
operation- The IOCBs used for CONSECUTIVE 
organization do not contain hidden buffers, 
except when V- format records are employed. 
Hidden buffers are used in this case so 
that the V- format control bytes can be 
eliminated from the record before the data 
is moved into the record variable. If, 
however, the data set consists of F-format 
unblocked records, and the size of a record 
variable is less than the fixed size of 
data set records, a temporary buffer area 
is dynamically obtained. The use of a 
temporary buffer area for input prevents 
the destruction of data following the INTO 
area; for output, it prevents triggering of 
the fetch-protect interrupt. 



comparing keys and raising the KEY 
condition is repeated in successive 
statements that refer to the file until the 
embedded key has been changed. (After a 
LOCATE statement has been executed, no 
further operations are possible on the file 
until the record has been transmitted; for 
records with embedded keys, this cannot 
occur until the KEYFROM string matches the 
embedded key.) 



When a file is closed implicitly (i.e., 
on termination of a task), the KEYFROM 
string overwrites the key part of the 
record in the buffer, and the record is 
written onto the data set. If the KEYFROM 
string is not identical with the embedded 
key, a message is printed out at the 
console. 



INDEXED Data Sets 



The access methods employed for this 
organization are QISAM and BISAM; they are 
used thus: 

QISAM: SEQUENTIAL creation and access 
BISAM: DIRECT access 

All usage of INDEXED data sets requires the 
presence of buffers, even though the file 
is UNBUFFERED or DIRECT. The buffer is 
required in order to deal with a 10-byte 
overflow record link-field. Only F- or 
V- format records, blocked or unblocked, are 
permitted. 

QISAM (IHEITD/IHEITN) : SEQUENTIAL creation 
and access of INDEXED data sets is 
performed using this access method. 
Creation requires that keys be presented in 
ascending collating sequence. The sequence 
is checked by the library before the PUT 
macro is executed, in order to synchronize 
a given WRITE statement with the raising of 
the duplicate KEY condition. This 
arrangement is necessary because, since PUT 
LOCATE is employed, QISAM would normally 
raise the condition only on the subsequent 
PUT operation. 

For records with embedded keys, when a 
WRITE statement with a KEYFROM string 
shorter than the key length, or a LOCATE 
statement, is executed, the KEYFROM string 
is placed in an area addressed by TPKA in 
the FCB. In the next operation on the file 
after a LOCATE statement (including a CLOSE 
statement) , the KEYFROM string is compared 
with the key embedded in the data in the 
buffer. If they are unequal, the KEY 
condition is raised. On normal return from 
the on-unit, control passes to the next 
statement in the program (i.e., the one 
following that which caused the KEY 
condition to be raised). The process of 



To support the REWRITE statement without 
the FROM option, the key is saved on 
execution of a READ statement with the SET 
option. When the REWRITE statement is 
executed, if the embedded key is the same 
as the saved key, a PUTX macro instruction 
is issued. If the key has changed, the 
PUTX macro is not issued and the KEY 
(specification) condition is raised. 



To support the DELETE statement without 
the KEY option, the first byte of the 
logical record is set to X'FF* and a PUTX 
macro instruction is issued to rewrite the 
record. 

If the file has the KEYED attribute, and 
the mode is INPUT or UPDATE, the QISAM SETL 
function is required in order to reposition 
the indexes. The parameters for the SETL 
macro are such that, for unblocked records, 
the recorded key is transmitted as well as 
the data record. For a READ statement, if 
the KEY string is shorter than the key 
length, the string is placed in an area 
addressed by TPKA in the FCB. If the file 
is not KEYED (indicating that the KEY 
option will not be employed) , the QISAM 
SETL routine is not loaded during the open 
process. 

Since buffers are employed, truncation 
or padding of records is performed during 
the move between the buffer and the record 
variable. Padding bytes are undefined in 
value. 

Closing a data set being created or 
updated by QISAM may cause output records 
to be written. If an error occurs, output 
entry to the SYNAD routine is prevented by 
the close process having cleared the 
DCBSYNAD field before issuing the CLOSE 
macro. The operating system uses the ABEND 
macro to terminate the task. 
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BISAM in a Non-Multitasking Environment 
(IHEITE/IHEITM): When the TASK option is 
not employed, direct access of INDEXED 
files, both exclusive and non- exclusive, is 
performed by modules IHEITE/IHEITM. For an 
exclusive file, IHEIOG treats the UNLOCK 
statement as 'no operation' (although it 
may implicitly cause the file to be 
opened) ; the NOLOCK option is ignored by 
IHEITE/IHEITM. 

BISAM requires the use of DECBs to 
communicate information regarding each I/O 
operation requested of it; see 'I/O Control 
Block (IOCB) * for details of the DECB and 
its use in BISAM. 

Since the EVENT option may be employed, 
and, moreover, the KEYFROM or KEY 
expression may yield a character- string 
value in temporary storage, the key value 
is moved into the buffer before BISAM is 
invoked. Truncation or padding of the 
character-string key to conform to the 
KEYLEN specification is performed during 
the move. A further reason for the move is 
that BISAM may destroy the contents of the 
key and record fields when adding new 
records to a. data set. 

If the data set consists of unblocked 
records, a READ statement need not precede 
a REWRITE statement. If blocked records 
are used, the sequence must be READ, then 
REWRITE, since the READ macro instruction 
has the KU parameter, and BISAM requires 
this type of READ to be rewritten. The 
WRITE K macro instruction used to rewrite 
the updated block must address the same 
DECB (IOCB) as that used for the READ KU 
macro instruction. This is achieved by not 
freeing the IOCB used for the READ 
operation. On the next operation on the 
file, a check is made for such an IOCB: if 
one exists, ,and the operation is not a 
REWRITE specifying the same key, the ERROR 
condition is raised. 

A DELETE statement is implemented by 
first issuing a READ KU macro instruction, 
then setting the first data byte to X'FF', 
and finally rewriting the record with a 
WRITE K macro instruction. 

BISAM in a Multitasking Environment 
(IHEITH/IHEITO): To ensure that the 
initialization and chaining of event 
variables, IOCBs, and exclusive blocks 
cannot be interrupted, the interface module 
IHEINT raises the dispatching priority of 
the current task to its limit before 
calling IHEITH/IHEITO. IHEITH/IHEITO 
restore the priority to its original value 
before executing an I/O macro instruction. 
The formats of the event variable and the 
exclusive block are described in Appendix 
I, which also includes an example of the 
chaining of these blocks. 



For non-exclusive files, modules 
IHEITH/IHEITO perform the same functions as 
IHEITE/IHEITM, and in addition chain any 
event variables that are made active. Each 
event variable is placed in. a chain 
anchored in the pseudo-register IHEQEVT in 
the PRV for the current task. This chain 
enables 1/0 event variables for which a 
WAIT statement has not been executed to be 
set complete, inactive, and abnormal when 
the task is terminated. 

The implementation for exclusive files 
includes the following additional features: 

1. Files with unblocked records : When any 
operation referring to a record 
(except WRITE and UNLOCK) is 
initiated, the chain of exclusive 
blocks anchored in the TXLV field of 
the FCB is searched for an existing 
exclusive block established in the 
current task for the record. If one 
exists, the lock statement count 
(XSTC) in the exclusive block is 
incremented by one. If there is no 
exclusive block, one is created in 
subpool 1 and inserted in the task 
chain (anchored in pseudo- register 
IHEQXLV in the current task) and the 
file chain (anchored in the TXLV field 
of the FCB of the current file) . The 
lock statement count is set to one, 
and the lock bit (XLOK) to one (unless 
the operation is READ with NOLOCK) , 
and the resource is enqueued (i.e. 
the record is locked) . After control 
of the resource has been obtained, it 
is dequeued if XLOK = 0. The qname 
and rname given in the ENQ and DEQ 
macro instructions are: 

qname (two words) : 
Byte 0: Zero 
Bytes 1-3: A(FCB) 
Bytes 4-7: Zero 

rname ( one word) : 
Byte 0: X'03' 
Bytes 1-3: A (Record key) 

After the CHECK macro instruction for 
the I/O operation has been executed 
(i.e., on execution of the WAIT 
statement if the EVENT option is 
used) , IHEITH/IHEITO raise the 
priority of the current task to its 
limit, decrease the lock statement 
count by one, and then: 

1. If the record is no longer locked 
(XLOK=0) and the lock statement 
count is zero, dechain and free 
the exclusive block. 

2. If the record is still locked 
(XL0K=1) , unlock it (unless the 
statement is READ without the 



I 
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NOLOCK option) , and set XLOK to 
zero. If the lock statement 
count is zero, they then dechain 
and free the exclusive block. 



IHEITH/IHEITO then restore the 
dispatching priority to its original 
value. When processing V- format 
records using IHEITO, the READ, WRITE, 
REWRITE, and DELETE statements are 
restricted as in 2 below. 



Files with blocked records : To prevent 
other tasks interfering with the READ, 
REWRITE sequence, each READ, WRITE, 
REWRITE, and DELETE statement is 
enqueued on the same resource (i.e., 
there is only one exclusive block for 
each file in each task, and it is not 
freed until the file is closed) . 
Control of the resource is retained by 
a given task until the WRITE, REWRITE, 
or DELETE operation is completed; or, 
if the resource was enqueued by a READ 
operation, until a REWRITE or UNLOCK 
statement is executed. When a READ 
statement with the NOLOCK option is 
executed, the resource is dequeued 
immediately after the task gains 
control of it. 



The qname and rname given in the ENQ 
and DEQ macro instructions are: 



qname (two words) : 
Byte 0: Zero 
Bytes 1-3: A(FCB) 
Bytes 4-7: Zero 



rname (one word) : 
Byte 0: X'03 f 
Bytes 1-3: A(FCB) 

Apart from these differences, the 
implementation is as for files with 
unblocked records. 



REGIONAL Data Sets 



The access methods employed for these 
organizations are BSAM and BDAM, as 
follows: 

BSAM: Creation and SEQUENTIAL access 
BDAM: DIRECT access 

Keys supplied by the source code are 
termed * source keys • . These have two 
formats, one of which is interpreted in two 
ways: 



Source key 
format 



O rganization 

REGIONAL (1) : 

Relative record addressing, 
without recorded keys 

REGIONAL (2): 

Relative record addressing, 
with recorded keys 

REGIONAL (3): 

Relative track addressing, 
with recorded keys 

Key Format A : 



r 1 

I M | 

L J 

< L > 

L = Length of key (1 through 255 

bytes) 
M = Key value 

Only the characters blank and to 9 may 
be used in M, which, when converted to 
binary, is the relative record position, as 
required for the BDAM BLKREF parameter. 
The last eight characters are scanned for 
an unsigned decimal integer representation; 
if less than eight characters exist, only 
the available characters are scanned, from 
left to right. 

When a format-A source key is required 
for the KEYTO option, the relative record 
position of the current record is converted 
from a binary count field into character 
representation and is assigned to the last 
eight characters of the KEYTO character 
string variable. If the variable has fewer 
than eight characters, the converted value 
is assigned, right to left , to the KEYTO 
variable. Format A keys are not appended 
to data set records as recorded keys. 

Key Format B : 

r t 1 

| C | M | 

L A J 

< L- > 

L = Length of key (1 through 255 

bytes) 
M = Last eight characters in the 

source key 
C = The remaining characters in the 

source key other than the M 

characters 

M consists of up to 8 characters, which 
can be blanks or to 9. When converted to 
binary, it represents either the relative 
record position (REGIONAL (2)), or the 
relative track position (REGIONAL (3)). 



Chapter 3: Input/Output 37 



If L < 8, C does not exist. The C 
characters can be any of the 256 characters 
available; they are not scanned. 

The format-B source key is appended to 
output records when they are added to the 
data set; the number of characters in the 
appended (recorded) key is determined by 
the KEYLEN specified for the data set. If 
KEYLEN is less than the length of the 
source key, the latter is truncated when 
appended to its record; if greater, the 
source key is padded with blanks. 
Similarly, when retrieving keyed records, 
the source key is altered to conform to 
KEYLEN. This permits 1 though L characters 
to be used as the recorded key. The M 
characters might thus be used only for 
computation of the relative record or track 
position. 

BSAM (IHEOPZ, IHEITC, IHEITB) : Creation 
and sequential access of REGIONAL data sets 
employs this access method. 

SEQUENTIAL creation is performed by the 
module IHEITC, which adds records to the 
data set in physically sequential record 
and track positions. This module also 
inserts dummy records, as required, by the 
user incrementing the source key position 
information by a value greater than one. 

When a sequentially created REGIONAL 
data set is closed, the current space 
allocation (which may be either the initial 
or a secondary allocation) is completed: 

1. by writing dummy records (F-format 
only) , or 

2. by setting the capacity records of the 
remaining tracks to indicate empty 
tracks. 

An FCB history flag (TMET) is turned on 
when, after writing a record, this record 
is seen to be the last one of an extent. 
If this flag is off, the close process will 
continue the initialization until an 
end-of -extent condition is met. 

When LOCATE statements are used to 
create a REGIONAL data set, an IOCB is 
selected from the pool in the normal 
manner. The KEYFROM string is evaluated, 
and all necessary formatting of the data 
set is done, before the pointer is set and 
control is returned to compiled code. To 
ensure that the record is always aligned on 
a doubleword boundary, the open process 
rounds up the keylength to a doubleword and 
allows space in the IOCB for the keylength 
and the block size. Module IHEITC places 
the key right-aligned in the key area, thus 
ensuring that the key and data are in 
contiguous areas, and that the data is 
aligned on a doubleword boundary. 



The record is not actually transmitted 
until the next statement on the file (e.g., 
CLOSE, WRITE, LOCATE) is executed. If it 
is found on transmission that there is no 
room for the record in the region 
(REGIONALO) V and U format records only), 
the capacity record is written and the KEY 
sequence error condition is raised. On 
normal return from the on- unit, control 
passes to the next statement. If this 
occurs when a file is closed implicitly (on 
termination of a task) or explicitly, a 
warning message is printed and the file is 
closed (after the initialization of the 
current extent has been completed) . Note 
that it is therefore possible that the 
original record associated with the LOCATE 
statement may not have been written. 



DIRECT creation requires the 
initialization of the data set during the 
open process; this is performed by the 
module IHEOPZ. Subsequently, records may 
be added to the data set in a DIRECT 
fashion using module IHEITF or IHEITJ. 
Initialization of a data set for DIRECT 
creation causes : 



the initial space allocation 
(secondary allocation is ignored) to 
be written with dummy records 
(F-format records, for all REGIONAL 
types) , or 



the capacity record of each track of 
the initial space allocation to be set 
to indicate empty tracks (U- format or 
V- format records, REGIONAL (3), only). 



If recorded keys are required, dummy keys 
(initial byte X'FF*, remaining bytes 
undefined) are also written for F-format 
records only. If during the initialization 
for DIRECT creation an error arises, the 
UNDEFINEDFILE condition is raised, the type 
of error being indicated by the ONCODE 
value. 



As SEQUENTIAL access of a REGIONAL data 
set (module IHEITB) is performed with BSAM, 
it is not possible to support the KEY 
option on the READ statement. The KEYTO 
option is supported as follows: 



REGIONAL (1) : 

A counter (the TREL field in the FCB) 
beginning at zero, is incremented as 
each record, including dummy or deleted 
records, is read; this is converted to 
character string representation and 
assigned to the KEYTO variable. 
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REGIONAL (2) and (3): 

The recorded key is read in with the 
record, and assigned, without 
conversion, to the KEYTO variable. 
Transmission of the recorded key only 
occurs if the file has the KEYED 
attribute; otherwise the KEYLEN DCB 
field is forced to zero to prevent 
input of keys (since, for F or U 
records, there are no hidden buffers). 



For both SEQUENTIAL creation and access, 
BSAM requires the use of DECBs to 
communicate information regarding each I/O 
operation requested of it; see 'The I/O 
Control Block (IOCB) • for details of the 
DECB and its use for BSAM. When REGIONAL 
data sets with the UNBUFFERED attribute are 
accessed (IHEITB) or created (IHEITC), 
hidden buffers are present in all cases 
except for REGIONALM), since the key and 
data must be within a contiguous area in a 
buffer. 



When reading REGIONAL data sets 
sequentially, BSAM retrieves all records 
within the data set, whether dummy 
(deleted) or actual records. For REGIONAL 

(2) and (3) data sets, the library prevents 
dummy (deleted) records being passed to the 
PL/I program. This is achieved by 
inspecting the initial byte of the recorded 
key as transmitted to the hidden buffer. 
(Hidden buffers are always required for 
KEYED SEQUENTIAL access of REGIONAL (2) and 

(3) data sets, because BSAM requires that 
the recorded key and the record be 
transmitted into contiguous storage areas.) 



If the initial byte is the dummy, or 
deleted, code (X'FFM, the IOCB chain is 
reorganized to move each input request down 
one entry in the chain; this resynchronizes 
the READ statements with the actual 
records. The reorganization occurs each 
time such a flagged key is detected. This 
technique is not available for REGIONAL 
(1), since for this type of organization: 

1. there is no way of knowing whether the 
records are actual or dummy, since 
there are no restrictions regarding 
the initial byte of the data record, 
and 

2. there are no recorded keys. 



BDAMdHEITF and IHEITJ) ; DIRECT access to 
a REGIONAL data set employs this access 
method, the usage depending upon the 
REGIONAL type: 

REGIONAL ( 1 ) : 

Relative record (block) addressing, 
no key argument 

REGIONAL (2) : 

Relative record (block) addressing, 
with key search argument 

REGIONAL (3) : 

Relative track addressing, 
with key search argument 

In the instance of REGIONAL (2) and (3), 
the "extended search" feature is always 
employed, A user may control the effects 
of extended search by using the DCB 
subparameter LIMCT; a value may be 
specified to limit the number of records or 
tracks which are searched for a given keyed 
record, or for space to add one. Unless so 
limited, searching for records extends 
throughout the complete data set. 

The BDAM access method requires the use 
of DECBs to communicate information 
regarding each I/O operation requested of 
it; see 'I/O Control Block (IOCB) f for 
details of the DECB and its usage for BDAM. 
If V format records are used, any IOCB 
created will contain a hidden buffer. 

The BDAM CHECK macro is issued to check 
that the operation is complete. If an 
error is found, the BDAM modules enter the 
IHEITF SYNAD routine, where the error is 
interrogated. 

If the TASK option is not used, direct 
access of REGIONAL files, both exclusive 
and non-exclusive , is performed by module 
IHEITF. For an exclusive file, IHEION 
treats the UNLOCK statement as *no 
operation* (although it may implicitly 
cause the file to be opened) ; the NOLOCK 
option is ignored by IHEITF. 

If the TASK option is employed, module 
IHEITJ is loaded instead of IHEITF. The 
difference between these modules is the 
same as that between IHEITE and IHEITH for 
unblocked records. (See * BISAM in a 
Multitasking Environment' . ) 



TELEPROCESSING Files 



When a READ statement with the SET 
option is executed for REGIONAL files, the 
data is always aligned on a doubleword 
boundary in the IOCB buffer. 



The implementation of the teleprocessing 
feature employs the queued teleprocessing 
access method (QTAM), which handles the 
transmission of messages between the 
operating system and remote terminals. 
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Messages accessed by QTAM are handled by 
two kinds of program: 

1. the message control program, and 

2. the message processing program. 

PL/I supports the message processing part 
of QTAM through process queue facilities, 
full descriptions of which can be found in 
IBM System/360 Operating System: QTAM 
Message Processing Program Services and IBM 
System/360 Operating System: QTAM Me ssage 
Control Program . 

QTAM (IHEITP) : To the PL/I user, the 
process queues appear as TRANSIENT 
SEQUENTIAL RECORD FILES , and are processed 
by means of the PL/ I READ, WRITE and LOCATE 
statements. 

Additional language required for this 
feature is: 

TRANSIENT file attribute on DECLARE or 
OPEN statements. 

ON PENDING (filename) on- unit. 

Note : the TRANSIENT attribute conflicts 
with the following attributes: - 

STREAM 

PRINT 

UPDATE 

DIRECT 

BACKWARDS 

EXCLUSIVE 

UNBUFFERED 

New environment options required are: 

G(max. length) : record format is a whole 
message, or 



under 'Record Oriented I/O' in this 
chapter . 



OPEN/C L OSE Fun c tions i n Te lep r ocessin g 



OPEN: the open process will be the same as 
for other record-oriented files discussed 
earlier in this chapter with the following 
additional functions :- 

1. Test for conflict between TRANSIENT 
and other attributes 

2. Create an FCB as previously but with a 
DCB for QTAM. The max. length value, 
as specified in the ENVIRONMENT 
attribute, will be placed in the field 
DCBSOWA of the DCB, and the number of 
buffers specified in the ENVIRONMENT 
attribute will be set in the DCBBUFRQ 
field. (If no buffers are specified, 
the default number is two.) 

3. Take the DCB exit as for other files 
and test the following fields: 

a. DCBBUFRQ - if this is still not 
set, either by the ENV attribute 
or by DD card, then apply the 
default of two 

b. DCBSOWA - if this field is empty, 
because the max. length has not 
been set in the ENV attribute, 
raise the undefined file condition 

c. DCBRECFM - if the record format 
has not been specified, raise the 
undefined file condition. 



R(max. length) 



i record format is a 
segment from a message 



(max. length being the maximum size of 
message segment or record to be read. This 
value will be set in the halfword DBLK of 
the DCLCB, with information on the format 
(G or R) and an indicator showing the file 
to be of teleprocessing organisation (see 
Appendix I)) . 

Bit of flag B (the second byte) of the 
open control block (OCB) will be set if the 
TRANSIENT attribute appears in the OPEN 
statement, and bit 4 of the DCLB byte of 
the DCLCB will be set if it appears in the 
DECLARE statement. 

The options KEYTO (character 
string-variable) and KEYFROM (expression) 
are also acceptable under a teleprocessing 
environment, used with record I/O READ, 
WRITE and LOCATE statements. The compiler 
deals with these statements as discussed 



t. Assuming the tests carried out above 
do not raise error conditions, the 
OPEN exit routine additionally issues 
a GETMAIN macro instruction for an 
area large enough to hold the longest 
terminal identification plus the max. 
length of message plus four bytes for 
control information for QTAM 
(8 + DCBSOWA +4). The address of 
this area will be held in the DCBTRMAD 
field of the DCB. The first eight 
bytes of the GETMAIN area will be used 
for holding the terminal name, and the 
remainder as an intermediate (dummy) 
buffer for messages. The address of 
the 'message buffer* will be kept in 
the FCB (in the TSWA field). 

5. Load the teleprocessing transmitter 
module IHEITP and set the first word 
in the FCB for valid statements as is 
the case for other files. The bits • 
set and the statements they refer to 
are: 



HO 



for input: bit 1 - READ SET KEYTO 
bit 4 - READ INTO KEYTO 



to X'02* to indicate the end of the 
message. 



for output: bit 14 - WRITE FROM KEYFROM 
bit 23 - LOCATE SET KEYFROM 



CLOSE : The close process again will be 
similar to previously described functions, 
but additionally will check to see if the 
last operation on the file was LOCATE. If 
so, the close module will invoke the 
transmitter to write out the last record. 
This is in line with the general rules of 
the PUT MOVE mode which is used by this 
implementation. 



The close routine, after the last record 
is written out, will delete module IHEITP 
which was loaded at OPEN time. 



I/O Statements for Teleprocessing 



All I/O statements on TRANSIENT files 
invoke module IHEITP through modules IHEION 
(non-multitasking) and IHEINT 
(multitasking). The latter two modules 
will carry out tests on the validity of 
such I/O statements as described under 
"General Logic and Flow" in this section. 

Input : The transmitter will issue a QTAM 
•GET* macro instruction to read the next 
sequential instruction on the file, and 
record and terminal identification will be 
placed in the •dummy* buffer. The length 
of the data read will be found in the first 
two bytes of the four byte control 
information area. For SET options, the 
pointer will be set to point to the data in 
the dummy buffer. The data will be aligned 
on a doubleword boundary. 

The terminal identification will be 
moved into the KEYTO string. If the length 
of the identification field is less than 
the KEYTO length, it will be padded with 
blanks, unless the KEYTO string is varying, 
in which case only the current length will 
be set. If the length of the 
identification field is greater, it will be 
truncated. 

Output : The sequence of operations for 
output is very similar to those for input, 
using a QTAM 'PUT* macro instruction 
instead of 'GET*. The data and terminal 
identification are placed in the dummy 
buffer in the same way, with the control 
information set; additionally, the third 
byte of the control information will be set 



Only the first eight characters of the 
KEYFROM string will be moved into the 
buffer. If there are less than eight 
characters in the string, the string will 
be padded with blanks to fill all eight 
positions. The RECORD condition will be 
raised (when necessary) in accordance with 
the rules for V-format records. 



Error Handling 



With the addition of the ON-conditions 
listed below, the error handling routine 
for teleprocessing files follows the same 
course as for other record-oriented files 
(for a discussion on ON-conditions, see 
chapter 6: "Error and Interrupt Handling"). 



The ON-conditions associated with 
teleprocessing are: 

1. ON TRANSMIT (filename) - could be 
raised for input only 

2. ON RECORD (filename) - could be raised 
as for other files. The records in a 
teleprocessing file would be treated 
as V-format records with the 
corresponding rules applying. 

3. ON ERROR - could be raised as for 
other files with one additional 
condition. If the KEYFROM string is 
invalid or missing, then an error 
condition with an ONCODE of 1020 will 
be raised. 

4. ON PENDING - is very similar to the ON 
ENDFILE condition, with QTAM passing 
control to the user through an EODAD 
exit routine. If EODAD is not 
supplied, then QTAM 'waits' until more 
data is available. The normal return 
from the on- unit which implies this 
'wait* will be implemented as follows: 

a. Take EODAD exit 

b. Raise PENDING condition (when 
normal return, then) 

c. Zero EODAD field and re- execute 
GET macro 



d. 



Reset EODAD to the correct exit 
routine address. 
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CHAPTER 4: PL/I OBJECT PROGRAM MANAGEMENT 



INTRODUCTION 



The PL/I Library provides facilities for 
the dynamic management of PL/I programs. 
This involves: 

1. Program management ; Housekeeping at 
the beginning and end of a program or 
at entry to and exit from a block. 

2. Storage management ; Allocation and 
freeing of storage for automatic and 
controlled variables, and for list 
processing. 

This section describes the requirements 
for these facilities and their 
implementation by the library. With the 
exceptions of the compiler optimization 
routine and storage management for list 
processing, all the functions described are 
performed by module IHESAP, whose entry 
points are listed in Figure 16; full 
details are given in Chapter 9. Object 
program management in a multitasking 
environment is discussed in Chapter 5. 



supervisor on entry to the program, 
functions are: 



Its 



Entry point 



IHESADA 
IHESADB 
IHESADD 
IHESADE 
IHESADF 
IHESAFA 
IHESAFB 
IHESAFC 
IHESAFD 
IHESAFF 
IHESAFQ 
IHESAPA 
IHESAPB 
IHESAPC 
IHESAPD 
IHESARA 
IHESARC 
IHESATA 



Function 

Get DSA 

Get VDA 

Get controlled variable 

Get LWS 

Get library VDA 

END 

RETURN 

GO TO 

Free VDA/Free LWS 

Free controlled variable 

Abnormal program termination 

Program initialization 



Environment modification 
Setting of return code 
STAE exit for 0/S abnormal 
termination 



Allocation of storage for the PRV. 
(See 'Communications Conventions' in 
Chapter 2.) 

Initial allocation of LWS. 

Passing of the address of the library 
error- handling subroutine (IHEERR), 
which assumes control when an 
interrupt occurs, to the supervisor. 



Block Housekeeping; Prologues and Epilogues 



Prologues and epilogues are the routines 
executed on entry to and exit from a PL/I 
procedure or begin block. The library 
subroutines contain those sections that are 
common to all prologues and epilogues. The 
functions of the library prologue 
subroutine are: 

1. To preserve the environment of the 
invoking block. 

2. To obtain and initialize automatic 
storage for the block. 

3. To provide chaining mechanisms to 
enable the progress of the program to 
be traced. A detailed description of 
the chaining mechanisms employed is 
provided below. 

The main functions of the epilogue 
subroutine are: 

1. To release storage for the block. 

2. To recover the environment of the 
invoking block before returning 
control to it. 



■ 



| Figure 16. IHESAP Entry Points 



Storage Management 



Program Initialization 



Certain functions must be carried out on 
entry to a PL/I program before the PL/ I 
main procedure is given control. One of 
the library program- initialization 
subroutines is always given control by the 



In IBM System/360 Operating System, storage 
is obtained or freed by using the GETMAIN 
and FREEMAIN macros. The library assumes 
responsibility for obtaining and freeing 
storage in this way in order to: 

1. Provide an interface between compiled 
code and the control program. 
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2. Reduce the overhead involved in making 
a supervisor call every time storage 
is obtained and freed. 

3. Set up chaining mechanisms for dynamic 
storage. 

There are three types of dynamic storage 
in PL/I, controlled, automatic, and based. 
Based storage is discussed in 'List 
Processing: Storage Management*. 



Operating- System Facilities 



AUTOMATIC STORAGE: STORAGE MANAGEMENT 



Two types of automatic storage area are 
needed to implement the functions described 
above. These are: 

1. The storage area associated with the 
execution of a PL/I block, known as a 
dynamic storage area (DSA) . 

2. The storage area mainly used for 
automatic variables whose extents are 
unknown at compile time, known as a 
variable data area (VDA). 



The following facilities appropriate to 
this chapter are provided by IBM System/360 
Operating System. (See IBM System/36 
Operating System: Supervisor and Data 
Management Macro Instructions . ) 

SPIE macro instruction : Specifies the 
address of a routine to be entered when 
specified program interrupts occur. 

STAE macro instruction : specifies the 
address of a routine to be entered when a 
task terminates abnormally. 

ABEND macro instruction : Causes a job step 
or task to be terminated abnormally. 

Write To Operator (WTO) macro instruction : 
Can be used to write a message on the 
operator's console. 

R-type GETMAIN : Requests that the 
supervisor allocate a contiguous block of 
maiifi storage to the caller. A subpool 
number should be specified. (See below.) 

R-type FREEMAIN : Releases a main storage 
area. The length, subpool number, and 
address of the beginning of the area must 
be specified. 

Subpools : Subpool numbers are of 
significance only in an operating system 
with MVT. 

Subpool zero 

The storage in subpool zero is allocated 
on a job-step basis, and is never 
automatically released until the end of 
the job step. 

Subpool non-zero 

The storage in a subpool with a non-zero 
number is allocated on a task basis, and 
is automatically released on the 
termination of the task that owned the 
subpool . 

IBM System/360 Operating System: 
Supervisor and Data Management Services 
contains, a full discussion of 
main-storage management. 



Each type of storage area is identified by 
flags set in the first byte. These flags 
also indicate the existence of certain 
optional entries in the storage area. The 
flag patterns are shown in Appendix J. 



Dynamic Stora ge Area (DSA) 



This area, always associated with the 
execution of a PL/I block, is used to 
record the progress and environment of a 
program. It also contains space for 
AUTOMATIC variables declared in the block 
and for various optional entries. The 
minimum size of a DSA is 100 bytes. The 
format is described in Appendix J. 

The address of the DSA associated with a 
particular block is held in a 
pseudo-register. Hence there is a 
pseudo-register for <»ach block; the group 
of these pseudo-registers is known as the 
dis play . The address contained in a 
display pseudo- register can be used to 
identify the DSA associated with a 
non-recursive block when a GO TO statement 
specifying a label in that block is 
executed. 

When a block is entered recursively, a 
new DSA is created for the invoked block. 
The address of the DSA associated with the 
previous invocation of that block is stored 
in the display field of the new DSA. This 
address is already stored in the 
appropriate pseudo- register, where it is 
now replaced by the address of the new DSA. 
When this latest invocation is finished, 
the new DSA is freed and the address of the 
previous DSA is restored to the appropriate 
pseudo- register. 

When there is a GO TO statement to a 
label in a recursive block or to a label 
variable, a unique means of identifying the 
block qontaining the label is needed. This 
is accomplished by means of an invocation 
count , which is stored in the 
invocation-count field in the DSA during 
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the prologue. The current invocation count 
is contained in a pseudo-register and is 
increased by one each time a DSA is 
obtained. 



Variable Data Area (VDA) 



A variable data area is a special type of 
automatic storage area used for variables 
whose extents are not known at compile 
time. This storage area is associated with 
the storage obtained for a particular 
block. The only housekeeping necessary is 
that which provides a means of 
identification of the type of storage area 
and a method of associating it with a 
particular block for epilogue purposes. 

VDAs are used for three other purposes: 

1. Temporary storage for library modules. 
These areas are only distinguishable 
from an ordinary VDA by the flag byte. 
This is to allow them to be freed on a 
GO TO, as described in the example in 
•DSA Chain* under 'Block 
Housekeeping' . 

2. The PRV and primary LWS are contained 
in a VDA known as the PRV VDA which is 
chained back to the external save 
area. 

3. Secondary LWS is contained in a 
special library workspace VDA. 

The formats of the VDA, PRV VDA, and LWS 
VDA are shown in Appendix J. 



Library Workspace (LWS) 



The housekeeping associated with library 
workspace can be divided into two parts: 

1. The identification of the area needed 
as library workspace, and chaining 
this to a previous allocation of 
automatic storage and to any previous 
library workspace. 

2. The updating of the pseudo-registers 
pointing at the various areas in 
library workspace. 

The first allocation of LWS is contained 
in the PRV VDA; subsequent allocations are 
contained in the LWS VDA . The 
pseudo-register IHEQLSA always contains the 
address of the current LWS. Save areas 
within LWS are indicated thus: 

1. The address of each save area is held 
in a pseudo- register. 



2. The beginning of each save area is 

indicated by X'60* in the first byte. 
(A DSA can often be readily 
distinguished from a save area in LWS 
by the presence of X'8' to X'F' in its 
first half byte. Appendix J includes 
the format of the first byte of the 
DSA.) 



All ocation and Freei ng of Aut o matic Storage 



This section describes the methods of 
controlling the allocation and freeing of 
automatic storage for VDAs, DSAs and 
secondary LWS. 

To minimize the number of supervisor 
calls necessary to obtain automatic 
storage, a fairly large block of storage is 
obtained every time a call is made. Areas 
are allocated by the library from this 
block as required until a request is made 
that is too big to be satisfied from the 
remaining storage in the block. Another 
block is then obtained by a call to the 
supervisor. So that a check can be made as 
to whether the amount of storage remaining 
in a block is sufficient to meet an 
allocation, a record of the amount is 
stored in the block. When a storage area 
is freed, its length is added to the 
available length in the block. When the 
available length equals the total length of 
the block, the block is returned to the 
supervisor. 

Since storage areas are released in the 
reverse order to their allocation, a 
chain-back mechanism, with a pointer to the 
last member of the chain, is provided. 

Initially, storage is allocated for the 
PRV VDA from a Ik or a 6k block. When 
further requests are made for storage, they 
are satisfied by allocations from the 
remaining storage of this block. When a 
request cannot be satisfied, a 2k block (or 
a block containing a multiple of 2k bytes) 
is obtained by means of a GETMAIN macro. 
This block is chained to the existing block 
by the free-core chain. (See Figure 17.) 

In any block that contains unallocated 
storage (that is, contains free core) , the 
first four words of the unallocated storage 
are used for control purposes: 

1st wor d: Length (in bytes) of the 

unallocated storage for that 
block (excluding the four 
control words) 

2nd wor d: Block length 

3rd word : A (Free core length in previous 
block) 
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Figure 17. Structure of the Free-Core Chain for Automatic Variables 




4th word ; A (Free core length of following 
block) 

The first and last blocks require a 
slightly different usage: 



First block; 



Uses the free-core 
pseudo-register IHEQSFC in 
the chaining forward and 
back; 

1. IHEQSFC contains 

A (Free-core length of 
first block) . 

2. 3rd word of block 
contains 

(A (IHEQSFC) - 12), which 
is a dummy free- core 
length in the PRV. 



Last block ; 4th word contains 

When a request for storage is received, 
a search of the free-core lengths, starting 
from the first, is made. If a free-core 
length equal to or greater than the length 
requested is found, the request is 



satisfied from that block. The free-core 
length and pointers are adjusted, as are 
the appropriate pointers in the blocks on 
either side. 

When storage is freed, the pointers are 
adjusted, and the free-core field in the 
corresponding block is updated. If a 2k 
block becomes available, it is freed by 
issuing a FREEMAIN macro, and the free-core 
chain pointers are adjusted accordingly. 



CONTROLLED STORAGE: STORAGE MANAGEMENT 



Controlled storage is used for controlled 
variables only; it is requested by the 
ALLOCATE statement and freed by the FREE 
statement. 

Allocation of a particular controlled 
variable may occur a number of times. 
Since the latest allocation is always the 
one to be used it is convenient to have a 
pseudo-register pointing at it; this 
pseudo- register is sometimes referred to as 
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Figure 18. Storage Allocation for a Controlled Variable 



an 'anchor word 1 . Each allocation is 
chained back to the previous allocation so 
that the pseudo- register can be updated 
when the current allocation is freed 
(Figure 18). The length of the data is 
recorded in the f ullword field following 
the chain-back address. The length of the 
data is 12 bytes less than the length of 
the allocation. The Task Invocation count 
is held in the TIC field. 



When there is no allocation, the 
contents of the pseudo-register are zero. 
Each allocation points to the previous 
allocation, the pointer being zero in the 
first allocation, which is at the bottom of 
the stack. Thus the various allocations of 
a particular controlled variable become 
part of a push- down (ALLOCATE) pop- up 
(FREE) list. 

When a request is made to storage 
management for a new allocation, it is 
serviced by issuing a GETMAIN macro. 
Twelve bytes are added to the length 
requested, for control purposes, and this 
new length is rounded up to a multiple of 
eight bytes. The length field contains the 
actual length requested. The 
pseudo-register is updated and points to 
word four of the area. When a request is 
made to storage management to free an 
allocation, it is serviced by updating the 
pseudo-register and issuing a FREEMAIN 
macro. 



Allocation and freeing of storage for 
based variables in programmer-defined 
areas (area variables) . 



Assignments between area variables. 



System Storage - Based Variables 



Storage for based variables is allocated 
and freed in a similar manner to controlled 
storage, but it is not stacked since each 
generation is associated with a particular 
pointer value: reference may be made to any 
current generation of based storage by 
associating the appropriate pointer value 
with the name of the based variable. A 
request for a new generation of based 
storage is serviced by issuing a GETMAIN 
macro, and storage is freed by the FREEMAIN 
macro. Based storage is allocated only in 
multiples of eight bytes: the sum of the 
length of the variable and its offset from 
a doubleword boundary is rounded up to a 
multiple of eight bytes. All based storage 
allocated in a task is freed at the end of 
the task. 



The AREA Attribute 



LIST PROCESSING: STORAGE MANAGEMENT 



This section describes the functions of 
module IHELSP, which controls the 
allocation and freeing of storage for the 
PL/I list-processing facility. The 
functions involved are: 

1. Allocation and freeing of system 
storage for based variables. 



The AREA attribute enables a programmer to 
define a block of storage (an area 
variable) in which he can collect and make 
reference to based data. Space within the 
area variable is requested and released by 
ALLOCATE and FREE statements that include 
an IN (area-variable) clause. Reference can 
be made to a based variable contained by an 
area variable just as if the based variable 
were in system storage. The contents of 
one area variable can be assigned to 
another area variable, and an area variable 
can be handled as a single data item in 
input/output operations. 
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Flags 



Length of AREA variable 



Offset of End of Extent 



Offset of Largest Free Element 



Zero if Free List 



Allocated 



Length of Free Element 



Offset of next smaller Free Element 



Allocated 



Length of Free Element 



Offset of next smaller Free Element 



Free 
Element 



Extent 



Free 
Element 



Allocated 



Not Allocated 



Figure 19. Format of Area Variable 
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The Area Variable 



The format of the area variable is shown in 
Figure 19. The start of the area is 
aligned on a doubleword boundary. The 
first four fullwords are used for control 
information, the remainder of the area 
being the storage requested by the 
programmer in declaring the area variable. 
The portion of the area that has been 
allocated to based variables is termed the 
extent . When storage is allocated to an 
area variable, its length is set in the 
last three bytes of the first word, and the 
second word (offset of end of extent) is 
set to zero. 



part of the area. If this, also, is too 
small, the AREA condition is raised. When 
an element is freed, it is placed in the 
free list according to its size. If it is 
contiguous with another free element, the 
two are merged and included in the free 
list as a single element. If the last 
element in the extent is freed, the extent 
is reduced and the element is not placed in 
the free list. 



Area Variables - Assigment 



Area Storage for Based Variables 



Storage for based variables within an area 
variable is allocated only in multiples of 
eight bytes; each such allocation is termed 
an element . The first request for storage 
for a based variable is satisfied by the 
allocation of the appropriate number of 
bytes starting at the beginning of the 
unused space; the offset of the end of this 
allocation is set in the second word of the 
area variable, which now points to the 
first available doubleword of unused 
storage. Providing no storage has been 
freed, further requests are met by further 
contiguous allocations from the unused 
space, the offset of the end of the extent 
being updated each time. 

If the last allocation of the extent is 
freed, the offset in the second word of the 
AREA variable is reduced. However, if 
allocations other than the last in the 
extent are freed, the extent is not 
reduced: spaces, termed free elements , are 
left. The length of each free element is 
set in its first fullword, and a pointer to 
the next smaller free element (in the form 
of an offset from the start of the area 
variable) is set in the second word. If 
there are no smaller free elements, the 
second word of the free element points to 
the fourth word of the area variable, which 
is set to zero. The chain of free elements 
is termed the free list , and is anchored in 
the third word of the area variable, which 
contains the offset of the largest free 
element. When an area variable contains a 
free list, the first bit of the flag byte 
is set to 1. 

Whenever storage in an area variable is 
to be allocated to a based variable, the 
free list is searched for the smallest 
element that will contain the based 
variable. If no free element is large 
enough, space is allocated from the unused 



When the contents of area variable A are 
assigned to area variable B, the current 
extent and the control words (except the 
length of A) are copied into B. If the 
length of B is less than the extent of A, 
the AREA condition is raised. 



The AREA Condition 



If an on-unit is entered when the AREA 
condition is raised during the execution of 
an ALLOCATE statement, the ALLOCATE 
statement is executed again after the 
on-unit has been terminated normally. The 
return address passed by compiled code is 
stored in the library communications area 
(WREA) before the on-unit is entered. On 
normal termination of the on-unit, IHEERR 
returns control to the address in WREA. 

If the AREA condition is raised during 
the execution of an assignment statement, 
the statement is not executed again. 



PROGRAM MANAGEMENT 



Initial i zation of a PL/I Program 



On entry to a PL/I program, one of the 
library initialization subroutines 
(IHESAPA, IHESAPB, IHESAPC , and IHESAPD) is 
always given control by the supervisor; the 
entry point that is used depends on the 
level of compiler optimization required 
(see below) and on whether the PL/I program 
is called from an assembler- language 
routine. The initialization routine first 
obtains storage for the PRV VDA. The 
length required is the sum of: 
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L(PRV) (passed by the linkage editor) 

L(LWS) (assembled by the initialization 
subroutine) 

8 control bytes 

Since a pseudo-register is referenced by 
the addition of a fixed displacement to the 
base address in register PR, and the 
maximum displacement allowed by the 
assembler is 4096 bytes, the length of the 
PRV is limited to 4096 bytes. This puts 
the upper limit on the combined number of 
blocks, files and controlled variables at 
about 1000. If the initialization routine 
is asked to get a PRV longer than 4096 
bytes, a message is printed out on the 
console and the program is terminated. 

The initialization routine zeros the 
PRV, sets up the LWS pseudo- registers, and 
issues a SPIE macro instruction naming 
IHEERR and a STAE macro instruction naming 
IHESTA. In addition, IHESAPA and IHESAPC 
enable a PARM parameter on the EXEC card to 
be passed to the PL/I program. (See IBM 
System/360 Operating System; Job Control 
Language User's Guide , and Job Control 
Language Reference . ) On exit from the 
initialization subroutine, register RA 
points at a location containing the address 
of the SDV of the parameter. 



Termination of a PL/ I Program 



Normal Termination; Normal termination of 
a PL/ I procedure is achieved by an END or 
RETURN statement, either of which involves 
releasing the automatic storage associated 
with the procedure. If a reguest is made 
to free a DSA which would entail freeing 
the DSA for the main procedure, IHESAFA 
(END) or IHESAPB (RETURN) raises the FINISH 
condition and the program branches to the 
error-handling subroutine (IHEERR) . If and 
when this subroutine returns control, 
IHESAFA or IHESAFB causes all opened files 
to be closed (by calling the library 
implicit-close subroutine) . Subsequently 
all automatic storage, including the PRV 
VDA, is returned to the supervisor. 
IHESARC is then called to set the return 
code and return control to the supervisor. 

Abnormal Termination; A PL/I program is 
considered to terminate abnormally when the 
FINISH condition is raised by any means 
other than a RETURN, END, or SIGNAL FINISH 
statement (e.g., when an object-time error 
occurs such that the ERROR condition is 
raised). If there is not a GO TO out of 
the ERROR or FINISH on-unit (if any), the 
error-handling subroutine (IHEERR) calls 
IHESAFQ, which closes all the open files in 



the manner described above; IHESAFQ returns 
to the supervisor with a return code of 
(2000 ♦ any return code already set (module 
1024)). 

System Termination; If the operating 
system schedules the abnormal termination 
of a PL/I program, such a termination will 
be intercepted and a message will be output 
on SYSPRINT if possible; alternatively the 
message will be output on the system 
console. Control will then be passed back 
to the abnormal termination routine of the 
operating system. 



GO TO Statements 



In PL/I, a GO TO statement not only 
involves the transfer of control to a 
particular label in a block but also 
requires the termination of contained 
blocks. The housekeeping requirements for 
this are: 

1. A return address. 

2. A means of identifying the automatic 
storage associated with the block to 
be made current. 

Identification of the appropriate storage 
depends on whether the environment is 
recursive or non- recursive; 

Recursive ; A count (the invocation count) 
is kept of the number of times 
any block is entered; this 
count can be used to identify 
the storage for a particular 
invocation . 



Non- recurs ive; 



The address of the storage 
for each block is required. 



On-Units and Entry- Parameter Procedures 



If, in a recursive environment, the program 
enters: 

1. an on-unit, or 

2. a procedure obtained by calling an 
entry parameter, 

that environment must be restored to the 
state that existed when the ON statement 
was executed or the entry parameter was 
passed. Similarly, at the exit from the 
on-unit or the entry-parameter procedure, 
the environment must be restored to its 
former state. 
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If the on-unit or entry-parameter 
procedure refers to automatic data in 
encompassing blocks, these references will 
be to the generations that existed when the 
ON statement was executed or the entry 
parameter was passed. These will not 
necessarily be the latest generations. 

The correct environment is obtained by 
restoring the display to what it was at the 
time the ON statement was executed or the 
entry parameter passed. 

When an on-unit is to be entered, the 
library error-handling subroutine calls 
IHESARA and passes it: 

1. The address of the on-unit. 

2. The invocation count of the DSA 
associated with the procedure 
containing the ON statement. 

When an entry- parameter procedure is to 
be called, compiled code branches to 
IHESARA and passes it: 

1. The address of the called procedure. 

2. The invocation count of the passing 
procedure. 

The state of the display at the time of 
passing is determined by examining the DSAs 
of active blocks invoked before the passing 
procedure. The display is modified and 
control is transferred to the called 
procedure. 

Before an on-unit or an entry-parameter 
DSA is freed, the display is restored, in a 
similar manner to that described above, to 
the state it had immediately before the 
on-unit was entered or the entry-parameter 
procedure was called. 



point at the last allocation in the chain. 
Initially it points at the PRV VDA. 
Register DR always points to the current 
save area. 



Consider a sample program. Successive 
areas are added to the chain thus: 

1. PRV VDA 

2. DSA (Main procedure) 

3. DSA (Procedure) 

4. DSA (Begin block) 



I 



r 1 

PR j PRV VDA j. > r 

>|. ) | 

| External 
| PRV 
IHEQLSA | 



LWS 1 
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| save area 
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j DSA 1 |<-J 
j (Procedure) | 
I _ __ I 

A 
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| DSA 2 j 
j (Procedure) j 
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Block Housekeeping 



The chaining of automatic storage areas is 
required both for housekeeping purposes and 
for storage management. In general, both 
these functions are satisfied by the 
automatic storage area chain (called the 
DSA chain or 'run time stack'). When a 
library module is entered, an offshoot of 
the DSA chain, known as the save-area 
chain, may be formed. 

DSA Chain: The DSA chain consists of the 
external save area, PRV VDA, DSAs and VDAs. 
DSAs are added to the chain as procedures 
and blocks are entered. VDAs are added to 
the chain after the DSA of the block in 
which they are required. The 
pseudo-register IHEQSLA is always set to 



j DSA 3 j 
| (Begin) j 






j 



Figure 20. Example of DSA Chain 

At this stage the storage map is as 
shown in Figure 20. If the begin block 
required a VDA this would be added to the 
end of the chain. Figure 21 shows an 
example in which the begin block required 
two VDAs. If the program now executes: 

1. An END statement : The storage in the 
chain is released, starting with the 
area pointed at by IHEQSLA and 
finishing when the current DSA has 
been released. This leaves the chain 
with items 1, 2 and 3 only. 
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2. A RETURN statemen t; All areas up to 
and including the immediately 
encompassing procedure DSA are 
released, leaving only items 1 and 2 



It is also possible to release the 
last VDA in a chain without releasing any 
other areas, by freeing the area pointed at 
by IHEQSLA. 



If a GO TO statement referring to a 
label in the main procedure had been 
executed when the situation was as shown in 
Figure 21, then either the invocation count 
or the display of the main procedure would 
be passed to the library subroutine 
(IHESAFC) . This would then search back up 
the chain until it found the DSA with that 
invocation count or display, and then make 
this DSA current. It would then free: 

1. All areas up to and including the DSA 
allocated after the DSA to be made 
current. 

2. Any library VDAs or LWS between the 
DSA to be made current and the 
following DSA. A VDA used by the 
library is distinguished from one used 
by compiled code by the flags in the 
first byte. (See Appendix J. ) 

A 
i , 



Save- Area Chain; When a PL/I block calls a 
PL/I Library subroutine, the save area 
passed is that in the DSA for that block. 
If the library routine calls a lower-level 
library routine, the save area passed is 
that of the appropriate level in LWS. Thus 
a save-area chain is built up as an 
offshoot of the DSA chain. (See Figure 
22.) Normally the save-area chain unwinds 
itself as control returns up through the 
levels; in the example, the chain would be 
left with DSAs 1, 2 and 3 remaining. 




IHEQSLA 

> r x 1 

VDA 



DSA 2 



Figure 22. Construction of the Save-area 
Chain 



DR | 

> r j. 1 
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| DSA 3 | 






I VDA 



IHEQSLA | 

> r L 



| VDA | 

I I 

l J 

Figure 21. Continuation of the DSA Chain 



Trea t ment of Interrupts; When a program 
interrupt occurs in a subroutine (library 
or compiled code) , the library 
error-handling subroutine (IHEERR) is 
entered and the address of the save area of 
that subroutine is set in register DR. 
(See Figure 23.) 

IHEERR calls IHESADE, passing its own 
save area, to get a new LWS (LWS2). If 
there is an on-unit corresponding with the 
interrupt condition, then, on return from 
IHESADE, IHEERR branches to IHESARA (which 
modifies the display) and passes it the 
save area LSA in LWS2. In turn, IHESARA 
branches to the on-unit and passes it the 
same save area. The prologue for the 
on-unit then calls IHESADA to obtain a DSA. 
The DSA chain can now continue if required. 
(See Figure 24.) 

If there is no on-unit corresponding to 
the interrupt condition, standard system 
action is taken. (See Chapter 6.) 

There are two possible ways of freeing 
the on-unit DSA; 
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1. 



By a GO TO statement from the on- unit. 
If the GO TO is to a statement in a 
block associated with DSA 3, or 
earlier, then the save-area chain can 
simply be forgotten. Registers are 
restored from the DSA to become 
current. 
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Figure 24. Structure of the DSA chain when 
the on- unit DSA is attached 



Figure 23. Structure of the DSA chain when 
the error-handling subroutine 
is entered after a new LWS has 
been obtained 



2. By the on-unit issuing a request to 

storage management to free the on-unit 
DSA. When this is done, control is 
returned to the error-handling 
subroutine at the point following that 
from which control was transferred to 
the on-unit. The error-handling 
subroutine restores DR in the normal 
way to point at LWE in LWS 1 and calls 
IHESAFD to free LWS 2. Control is 
then returned to the interrupted 
routine. In the example, the 
situation would now be as in Figure 
22. 



Object-time Optimization 



The compiler contains an optimization 
technique which minimizes the necessary 
housekeeping and provides faster execution 
of the prologue and epilogue. The 
technique can only be applied if the 
optimization option (OPT=01. Default) is 
specified for the compilation of the main 
procedure of a program. In this case, in a 
non-multitasking environment, a 512-byte 
storage area is reserved at the end of 
primary LWS during initialization and 
pseudo- register IHEQSLA is set to the 
address of that save area. The 
pseudo- register IHEQLWF contains the 
address of the reserved area attached to 
the current LWS. A reserved area is 
released only when its associated LWS is 
released. 
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Whenever a DSA is allocated for the A DSA allocated in the reserved area, or 

innermost procedure or procedures (at the a DSA allocated in STATIC storage at 

same depth) of a nest of procedures, the compile time, is identified by a 'One* in 

optimization technique will try to meet the the first bit of the second byte. (See IBM 

requirement from the reserved area. If Svstem/360 Operating System: PL/I (F) 

this is not possible (because the DSA Compiler. Program Logic Manual for a 

requires more than 512 bytes), the required discussion of DSAs in STATIC storage.) 
storage is obtained in the standard way, 
using IHESADA. 
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CHAPTER 5: PL/I OBJECT PROGRAM MANAGEMENT IN MULTITASKING 



INTRODUCTION 



PL/ I TASKS 



This section describes the facilities 
provided by the PL/I Library for the 
dynamic management of PL/I multitasking 
programs in an operating system with MVT. 
PL/I multitasking can be used in a 
multi jobbing or a multiprocessing 
environment. 



For multitasking, the program management 
module IHESAP is replaced entirely by the 
module IHETSA. Although some of the 
routines in IHETSA are peculiar to 
multitasking, most of them perform similar 
functions to the corresponding routines of 
IHESAP; Figure 25 compares the two modules. 
Only those features of IHETSA that are not 
included in IHESAP are described in detail. 
The library facilities for the multitasking 
pseud o- variables and built-in functions, 
and for the WAIT statement, are described 
at the end of this section; Appendix K 
gives full details of the PL/I control 
blocks for multitasking. 



All tasks created in a PL/I multitasking 
program are executed as subtasks of a 
common ancestor, the control task . The 
control task is the initial task which 
receives control from the operating system 
at the commencement of program execution. 
The use of a control task ensures that 
there is always present a task with a 
higher priority than that of the major 
task , the task for the main procedure. The 
control task can then be entered whenever 
it is necessary to terminate the major 
task, e.g. on execution of a STOP 
statement. Subsequent tasks attached by 
the major task are known as subtasks . 

The management of all tasks in the PL/I 
program is carried out by the control task. 
It creates and initializes the major task 
and any subtasks required and arranges for 
the termination of these tasks, either 
normally or abnormally. When multitasking 
is used in a multiprocessing environment, 
it is possible that two or more tasks may 
attempt to execute "soft" code (code which 
accesses or modifies control blocks) at the 



■ 



Function 



Entry Point s 
IHESAP IHETSA 



Get DSA 

Get VDA 

Get controlled variable 

Get LWS 

Get library VDA 

END 

RETURN 

GO TO 

Free VDA/ Free LWS 

Free controlled variable 

Abnormal program termination 

Program initialization 



Environment modification 

Setting of return code 

Initialization of major task 

CALL with task option 

EXTR (abnormal end-of-task exit routine-STAE exit) 

EXIT (PL/I abnormal end-of-task routine) 

Initialization routine for subtask 



IHESADA 
IHESADB 
IHESADD 
IHESADE 
IHESADF 
IHESAFA 
IHESAFB 
IHESAFC 
IHESAFD 
IHESAFF 
IHESAFQ 
IHESAPA 
IHESAPB 
IHESAPC 
IHESAPD 
I HE SARA 
IHESARC 



IHETSAD (Alias) 

IHETSAV 

See Note 

IHETSAL 

IHETSAW 

IHETSAE 

IHETSAR 

IHETSAG 

IHETSAF 

See Note 

IHETSAY 

IHETSAP (Name) 

IHETSAA (Alias) 



IHETSAN 
IHETSAC 
IHETSAM 
IHETSAT 
IHETSAX 
IHETSAZ 
IHESUBA 



Note; The allocation and freeing of controlled storage in a multitasking environment 
is handled by a separate module, IHETCV, which is called by compiled code. 

Figure 25. Comparison of IHESAP and IHETSA 
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same time. So that only one task may 
access "soft" code at any one time, the 
control task treats all tasks as subtasks 
of itself, and supervises these subtasks by 
a series of event control blocks; the POST 
event control block (PECB) and the WAIT 
event control block CWECB) for each task. 
A list of PECBs is kept by the control task 
in an ECBLIST which is checked every time a 
subtask requests access to soft code. When 
a request to execute soft code is made, the 
control task either POSTs the subtask to 
continue (if no other subtask is executing 
the same area of soft code) or, 
alternatively, keeps the requesting task in 
a WAIT state. On completing execution of 
the soft code, the subtask informs the 
control task which is then free to accept 
further requests. 



Note: The "soft* 
concerned with: 



areas of code are those 



1. Task Attachment 

2. End of task 

3. End of block with attached tasks 
*». PRIORITY pseudo-variable 

5. COMPLETION pseudo- variable and EVENT 
variable assignment 

6. WAIT statement 

7. OPEN statement 

8. CLOSE statement 

9. Exclusive block chaining 



TASK ATTACHMENT AND INITIALIZATION 



CONTROL TASK 



The control task is established at a 
priority (16*JSPRI+11) , where JSPRI is the 
priority specified in the JOB statement for 
the PL/I program. The presence of the TASK 
option in the PL/I main procedure statement 
causes the compiler to insert the name of 
one of the initialization routines of 
library module IHETSA into control section 
IHENTRY. At execution time, control is 
passed initially to IHENTRY which then 
branches to the initialization routine 
selected by the compiler (IHETSAA or 
IHETSAP) . Execution of the selected 
routine constitutes the control task. The 
control task obtains contiguous storage 
for: 



Its own save area and workspace (144 
bytes ) 



2. The event control block for the major 
task task variable (60 bytes) 

3. The PRV VDA for the major task. 

The length required for the PRV VDA is 
the sum of: 

1. Eight control bytes 

2. L(PRV) (passed by the linkage editor) 

3. L(LWS) (the total length of workspace 
initially required by the library) 



4. Four task-oriented words 

5. Task Communications Area (TCA) 
words long) 



(Four 



(If a PRV longer than 4096 bytes is 
requested, a message is printed out on the 
console and the program is terminated.) 

The format for the complete area of 
storage involved, with lengths, is shown in 
Figure 26. (Key numbers corresponding to 
the above are shown on the left of the 
Figure. ) 

Having allocated these storage areas, 
the control task: 

1. Uses the area allocated for the TASK 
variable of the major task, sets it 
active and initializes it, using an 
EXTRACT macro to obtain the limit and 
dispatching priorities from the TCB 
(task control block) set up for the 
control task by the operating system. 
(The TASK variable contains the task 
control information required by the 
PL/I Library). 

2. Creates an EVENT variable for the 
major task and sets it active. 

3. Sets up an ECBLIST (list of PECBs 
currently being waited on) in a 1024 
byte area. The ECBLIST initially 
contains only the address of the PECB 
for the major task. The ECBLIST 
continually expands and contracts as 
tasks are attached or detached, but 
when the ECBLIST becomes equal to 
zero, i.e. there are no further tasks 
to be attached or detached, control 
returns to the calling program (this 
would normally be the operating 
system) . 

4. Sets the CTECB (control task ECB) , the 
PECB and theWECB of the major task to 
zero. 
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L( bytes) 





72 

72 

28 

32 

1024 

4 
16 

8 

LPRV 

4 
4 
4 

LLWS 
16 




Standard Save 
Area 


j 






2nd. Save Area/ 
Workspace 


— 1 






Task Variable 








Event Variable 








ECBLIST 








CTECB 




5. 




Task Communications 
Area 




1. 


J. 


VDA Control 




2. 


PRV 













4. 











|. 


A(IHEZTASK) 




3. 


LWS 






Free Core 
Control 






Available Space 





DEC 
00 


L( bytes) 




16 


72 


8 



144 
172 
204 

1228 
1232 

1248 

1256 

1256 + 
LPRV 



1268* 
LPRV 

1268 

LPRV* 

LLWS 

1284 + 

LPRV* 

LLWS 



LPRV 



LLWS 



16 



Task Communications 
Area 



VDA Control 



PRV 



A(DSA of Attaching 
Task) 



ACPRWDA. of Attaching 
Task) 



A(Task Variable) 



A (Parameter List) 



Copied On-Slots 



Parameter List 



LWS 



Free Core Control 



Available Space 



SUBTASK 



DEC 
00 



16 



24 

24+ 
LPRV 

28 + 
LPRV 

32+ 
LPRV 

36+ 
LPRV 



40+ 
LPRV 



MAJOR TASK 



•Figure 26. Format of Storage Areas, Save Areas, etc. 
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5. Sets up the APLIST, which is a 
parameter list consisting of a return 
address and a parameter list address, 
to be passed to IHETSAM. 

6. Sets up an ECBLIST of two words 
containing the addresses of the ECB of 
the major task and the PECB of the 
major task. 

7. Attaches the module IHESUB at a 
priority one less than the control 
task. IHESUB then sets up a parameter 
list for IHETSAM and branches to 
IHETSAM (This method circumvents the 
use of the IDENTIFY macro, thus 
enabling the Linkage Loader to be used 
when desired) • 

Note ; IHETSAM receives control from IHESUB 
which is attached each time a new subtask 
is created (all tasks, including the major 
task, are considered subtasks of the 
control task in this context). Using the 
information stored in register RA, IHETSAM 
initializes the major task, a subtask or a 
message task, according to the values of 
RA: 

a. RA is negative: subtask 
initialized 

b. RA is positive and points to a 
fullword whose bit 0=0: major 
task initialized 

c. RA is positive and points to a 
fullword whose bit 0=1: message 
task initialized 

8. Waits on the two words in ECBLIST until 
one of them is complete: 

a. if the ECB of the major task has 
been posted, then an error has 
occurred which caused the 
operating system to terminate the 
task; in this case a message is 
put out and the program is 
terminated. 

b. the PECB of the major task has 
been posted. The control task 
determines the action it is to 
take from the code posted. 



CONTROL TASK SUBROUTINES 



and the subsequent action to be taken is as 
follows : 



DECIMAL 



1. (ENQUEUE) Control task is to go into 
a wait state until subtask has 
finished with a soft area of code 

2. 4 (ATTACH) Attach a new subtask 

3. 8 (PRIORITY) Change the priority of a 
specified subtask 

U. 12 (DETACH) Special detach routine for 
message tasks only. 

5. 20 STOP has been executed. 

These subroutines operate in the 
following way: 

1. Enqueue Subroutine 

This subroutine simulates an 
ENQUEUE/DEQUEUE by putting the control 
task in a WAIT state so that it is 
unable to service requests from other 
tasks until the subtask which 
requested the enqueue brings the 
control task out of the WAIT state. 
The functions of this subroutine are: 

a. (1) Set a bit 'on* in the FLAG 

byte of the TCA to indicate 
"ENQUEUED" 

(2) Set the completion code of the 
WECB of the subtask to allow 
it to continue 

b. Wait on CTECB until posted by 
subtask 

c. Zero the CTECB 

d. Go back to WAIT on ECBLIST. 

2. Attach Subroutine 

The functions of this subroutine are: 

a. If the TASK or EVENT variables are 
already active, post the WECB of 
the subtask with the appropriate 
error code and go back to wait on 
ECBLIST. 



Having passed control to IHETSAM (via 
IHESUB), the control task will go into a 
WAIT state on the two word ECBLIST. This 
wait may be resolved by a code posted in 
four of the thirty bits used for the POST 
CODE of the PECB of a subtask, or by 
termination of the major task. The code 



b. (1) Initialize the TASK and EVENT 
variables. If one or both do 
not exist, issue a GETMAIN 
macro for dummy TASK or EVENT 
variables and set a flag in 
the variables so they can be 
freed when the task is 
detached. 
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(2) Determines that there are not 
more than 254 active subtasks: 
if more than 254 active 
subtasks, post error code. 

c. Attach IHESUB with the correct 
priority 

d. IHESUB passes control to IHETSAM 

e. Wait on a two- word ECBLIST for 
either the task to terminate (due 
to no core being available) or 
until IHETSAM has completed the 
subtask initialization. The 
subtask will post back the address 
of its TCA when initialization is 
completed. 

f. Post the WECB of the attachors 
subtask with code to indicate no 
errors 

g. Go back to wait on ECBLIST. 

Priority Subroutine 

Since all tasks are now subtasks of 
the control task, any task can change 
the priority of any other task. To 
accomplish such a priority change, 
compiled code invokes entry point 
IHETPRA of module IHETPR. IHETPRA in 
turn requests the control task to 
effect the change via entry point 
IHETPRB. 

Therefore, the functions of this 
subroutine are: 



zero (i.e. task did not 
terminate abnormally) . In 
this case, the functions of 
the control task are:- 



(a) Remove the A(PECB) of the 
subtask from its ECBLIST 



(b) Detach the TCB of the 
subtask 



(c) Free the TASK and EVENT 
variables if they were 
dummy 



(d) Go and wait on the ECBLIST 



(2) The task to be detached is not 
the requesting task. In this 
case, step (d) above will be 
replaced by:- 



(d) Wait on CTECB again 

The remaining functions are the 
same. 

(3) The task to be detached is the 
requesting task and APLIST is 
non-zero (i.e. task 
abnormally ended) . In this 
case, the functions of the 
control task are:- 



a. Call IHETPRB to perform the 
priority change (see 'PRIORITY 
Pseudo- Variable' in this chapter) 

b. Post WECB of the subtask with zero 

c. Go back to wait on the ECBLIST 

a) Detach Subroutine for Non-Message 
Tasks 

A subtask always requests the 
DETACH function of the control 
task when it is enqueued (i.e. 
the control task is waiting on 
CTECB) . Therefore, the subtask 
must set a code in the CTECB to 
request the control task to DETACH 
a particular task. The CTECB is 
posted with a completion code 
equal to the address of the TCA of 
the task which is to be detached. 

There are three types of tasks to 
consider: 

(1) The task to be detached is the 
requesting task and APLIST is 



(a) Remove A(PECB) of the 
subtask from its ECBLIST 

(b) Issue a GETMAIN macro 
instruction. In this area 
set a flag to indicate to 
IHETSAM that a message 
task is to be initialised 
and to store the 
completion code statement 
number and offset. The 
attached task will link to 
IHETEXC, using the 
provided workspace. 

(c) Detach the TCB of the 
subtask and free dummy 
TASK or EVENT variables. 

(d) Attach IHESUB (IHETSAM) and 
add the address of its 
PECB (which is located in 
the GETMAIN area) to the 
ECBLIST of the control 
task. 

(e) Go and wait on the new 
ECBLIST 
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4. b) Detach Subroutine for Message 

Tasks 

This routine detaches the 
requesting message subtask and 
frees the core storage obtained 
for it. It then returns to wait 
on ECBLIST. 

5. STOP 

When STOP is posted, the control task 
sets a flag to indicate this and then 
goes to the ENQ subroutine. 



is invoked in case of a program 
interrupt 

A STAE (Specify Task Asynchronous 
Exit) macro is also issued which 
specifies IHETSAX as the exit routine, 
and the address of the TCA as the 
address of the STAE parameter list 

The pseudo-registers IHEQVDA, IHEQFVD, 
IHEQADC, IHEQCTS, IHEQTCA, IHEQSLA, 
IHEQSFC, and IHEQATV are then 
initialized 



INITIALIZATION OF MAJOR TASK 



INVOCATION OF SUBTASK 



When the major task initialization routine, 
IHETSAM, is attached (via the control task 
and IHESUB) it has a priority of one less 
than the control task. This has the effect 
of making the whole program appear to have 
a priority of one less than the operating 
system limit priority, which allows the 
control task to be posted and to assume 
control immediately. 

IHETSAM is similar to the 
non-multitasking initialization routine 
IHESAP (described in Chapter 4), but in 
addition: 

1. A flag bit (bit 8) in the PRV VDA is 
set to indicate that it is a 
multitasking PRV VDA 

2. The address of the task variable is 
placed in the PRV VDA and the other 
task-oriented words of the PRV VDA are 
set to zero (see Appendix K) 

3. A SPIE (Specified Program Interruption 
Exit) macro is issued which names the 
error-handling module, IHEERR, which 



When a CALL statement with a TASK, EVENT or 
PRIORITY option is executed, compiled code 
calls the library module IHETSAT, which 
requests the control task to attach the 
subtask specified in the CALL statement. 

When the PL/ I program includes the TASK 
or EVENT options in a CALL statement, then 
compiled code is generated which, at 
execution time, is used to initialize the 
TASK and EVENT variables. The 
initialization consists of setting TASK and 
EVENT variables inactive, inserting the 
address of the associated symbol table 
entry in the TASK variable and setting the 
STATUS half word in the EVENT variable to 
zero . Furthermore, compiled code would 
have created an argument list (Figure 27) 
and inserted its address in register RA. 

Pointers to the PRV and DSA of the 
attaching task are stored in the two words 
of the parameter list reserved for library 
use; they are used in chaining tasks in 
•mother-daughter* relationships' 

If the CALL statement includes a 
PRIORITY option, the sum of the relative 




4 
8 
12 
16 
20 
24 
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Flags J A(Task variable) 

A (Event variable) 
,. H 

Priority relative to attaching task 
A (called procedure) 
For library use 






For library use 

Argument list for called procedure 
(X^O* in first byte of last entry 
indicates end of list) 



i 



j 



Zero if no TASK option 

Zero if no EVENT option 

Flags = X'80' if no PRIORITY option 



X'80* if no argument list 



Figure 27. Parameter List for IHETSAT 
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priority from the parameter list supplied 
by the compiled code and the dispatching 
priority in the task variable of the 
attaching task is stored in the task 
variable of the subtask; if the sum exceeds 
the limit priority for the PL/I program 
(16*JSPRI+10) , the dispatching priority for 
the subtask is made equal to the limit. 
(See IBM System/360 Operating System: PL/I 
(F) Programmer's Guide for a discussion of 
priority in a PL/I program) . The limit 
priority of the attaching task is also 
placed in the task variable of the subtask. 
If there is no PRIORITY option, and a task 
variable exists, the dispatching priority 
in the task variable is assumed; if the 
task has a dummy task variable, the 
dispatching priority is the same as that of 
the attaching task at the time the subtask 
is attached. 



1. It copies the contents of the PRV of 
the attaching task into the PRV of the 
new subtask 

2- It initializes the pseudo-registers 
IHEQTCA, IHEQSLA and IHEQATV, and 
zeroes IHEQRTC, IHEQEVT, and IHEQFOP 

3. It copies any ON- fields in the DSA of 
the attaching task, and the procedure 
argument list (if one is being 
passed) , into the PRV VDA of the new 
subtask. 

4. It increments the pseudo- register 
IHEQTIC by one. (IHETSAM sets IHEQTIC 
to zero when it initializes the major 
task. Each time a new subtask is 
attached, IHETSAM adds one to the 
count in IHEQTIC; the count thus 
indicates the level of each task 
within the hierarchy) 

5. It issues a SPIE macro for IHEERRA 



INITIALIZATION OF A SUBTASK 



Module IHETSAT is called by compiled code 
when a subtask is to be attached. This 
routine stores the address of the PRV and 
DSA of the attaching task in the parameter 
list, and then stores the address of the 
parameter list in APLIST (in the TCR) . 
Having posted the control task to attach a 
subtask, IHETSAT waits until it is informed 
by the control task that the subtask has 
been attached or an error has been found. 
When the WAIT is satisfied, it tests to see 
if any errors were detected. If so, it 
raises the appropriate ERROR condition and 
branches to IHEERRC. If there are no 
errors, it returns normally to compiled 
code. 



6. It issues a STAE macro for IHETSAX. 

The control task is then posted to 
indicate the completion of the 
initialization routine and IHETSAM then 
branches to the address of the called 
procedure. 



MESSAGE TASK 



In the case of a message task being 
required, IHETSAM sets up register 1 to 
contain the address of the parameter list 
and then links to IHETEXB to put out a 
message. IHETSAM then asks to be detached 
by posting the control task and waits until 
detached. 



On being posted by IHETSAT to attach a 
subtask, the control task executes its 
attach subroutine which calls IHESUB. The 
subtask initialization routine, IHETSAM, 
receives control from IHESUB, which is 
attached each time a new subtask is 
created. At this time, register RA 
contains the complement of the address of 
the parameter list prepared by compiled 
code (Figure 27). This conforms to the 
previous discussion on the control task 
wherein it was stated "RA is negative; 
subtask initialized" . 

IHETSAM calculates the length of the PRV 
VDA and LWS required by the subtask and 
issues a GETMAIN macro instruction for the 
amount of storage needed (rounded up to a 
multiple of 2048 bytes) : 

Then it initializes the PRV VDA as 
follows: 



EXIT AND TERMINATION OF TASKS 



NORMAL TERMINATION OF h TASK 



A PL/I task can be terminated by the 
execution of any one of the statements END, 
RETURN, STOP and EXIT. 

The action taken by the library END, 
(IHETSAE) and RETURN (IHETSAR) routines is 
similar to that of the GO TO routine 
(IHETSAG); the action differs from that of 
the non- multitasking equivalents in that 
any tasks attached in the block being 
terminated must also be terminated. This 
termination is done by means of the CTECB 
DETACH routine (see 'Control Task 
Subroutines'). If the block to be 
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terminated is also the end of a procedure 
called with the TASK option, the control 
task is informed and the task is detached. 

If it is the end of the major task, the 
FINISH condition is raised and the program 
branches to the error-handling routine. 
The END or RETURN routine will, on 
completion, post the control task to detach 
the major task. Finally, when the ECBLIST 
has no entries left, control is returned to 
the calling program. 

The abnormal- end-of -task routine 
(IHETSAZ) is entered 



To obtain the name of the subtask for 
insertion in the message, IHETSAX locates 
the task variable of the subtask by 
initiating a save-area trace from the PRV 
of the current task. The address of the 
TCA of the abnormally terminating task is 
passed in a parameter list to the STAE exit 
routine along with the completion code. 



GO TO STATEMENTS 



1. From IHEERR when return is made from 
the error routine in a subtask or from 
the FINISH routine in the major task. 

2. When an EXIT statement is executed in 
any task, or 

3. When CALL IHEDUMT is executed in any 
task. 

IHETSAZ detaches the task, and any tasks 
that it has attached, in the manner 
described under 'GO TO Statements*. 

The end-of-program routine IHETSAY is 
entered when a STOP or CALL IHEDUMP 
statement is executed in any task. IHETSAY 
terminates all subtasks in the manner 
described under 'GO TO Statements* . In 
both cases, control passes back to the 
calling program, by way of the control 
task, at completion. 



The multitasking housekeeping routine for 
GO TO Statements (IHETSAG) differs from its 
non-multitasking equivalent only in that if 
control is transferred outside the block in 
which the statement occurs, any tasks that 
are attached in the blocks that are freed 
must be terminated. If any tasks have been 
attached in the block, the task variable 
chain pointer in the DSA will point to the 
task variable of the most recently created 
subtask. IHETSAG searches the chain 
through each DSA in each task until a task 
is found that has attached no subtasks; 
this task is then terminated by informing 
the control task that this task is to be 
detached. 

The process is repeated until all the 
tasks attached in the block, and their 
descendants, have been terminated. In the 
process, all storage associated with these 
tasks is returned to the supervisor, and 
all files opened in the tasks are closed. 



ABNORMAL END-OF-TASK EXIT ROUTINE 



If a task terminates abnormally, the STAE 
exit routine (IHETSAX) is called. IHETSAX 
is specified in the STAE macro and is 
invoked whenever a subtask is attached. 
The STAE exit routine firstly detaches all 
subtasks of the abnormally terminating task 
and then informs the control task of the 
condition of that subtask. An area of 
storage is obtained by the control task in 
which the name of the subtask and the 
completion code are stored. This storage 
area also contains space for a save area to 
be used by the message task. The control 
task detaches the terminating task and 
attaches a task which prints out a message 
(as described under * Control Task 
Subroutines') giving the name, if any, of 
the subtask, the operating system 
completion code, and, in the more common 
cases, an indication of the probable error. 
The message is put out on SYSPRINT if it is 
open, otherwise it is put out on the 
console. 



ON- UNITS AND ENTRY PARAMETER PROCEDURES 



The multitasking routine IHETSAN modifies a 
recursive environment when an on-unit or an 
entry parameter procedure is entered or 
ended. It differs from the 
non-multitasking routine (IHESARA) in two 
respects. 

1. the chain of recursive DSAs is 
followed back to the PRV of the major 
task, and 

2. if a CALL statement calls an entry 
parameter procedure with a task 
option, the address of the entry 
parameter is placed at the top of the 
parameter list, the address of IHETSAT 
is assigned to the entry parameter, 
and IHETSAN is called. When IHETSAN 
terminates, it points register RA at 
the IHETSAT parameter list and 
branches to IHETSAT. 
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CONTROLLED STORAGE 



The allocation and freeing of storage for 
controlled variables in a multitasking 
environment is handled by library module 
IHETCV. This module is independent of 
IHETSA and is loaded only if the CONTROLLED 
attribute is used. When storage is 
allocated, the task invocation count from 
pseudo-register IHEQTIC is stored in the 
first halfword of the controlled variable. 
Before a controlled variable is freed, its 
task invocation count is checked; if it 
does not correspond with the value in 
IHEQTIC for the task in which the statement 
occurs, the variable is not freed. 
Controlled storage is allocated in subpool 
if it is in the major task, and in 
subpool 1 if it is in a subtask. 



MULTITASKING PSEUDO- VARIABLES AND BUILT-I N 
FUNCTIONS 



Statements in which the STATUS 
pseudo- variable appears, or which contain 
the COMPLETION or STATUS built-in function, 
are executed from compiled code without a 
library call. 



COMPLETION PSEUDO-VARIABLE 



On execution of an assignment statement in 
which the COMPLETION pseudo- variable 
appears, the expression on the right-hand 
side is evaluated and converted to a 
bit-string of length 1, which is then 
stored at bit 2U of a fullword. Compiled 
code then calls IHETEVA, passing the 
address of the event variable named in the 
pseudo-variable, and that of the fullword 
(in a list pointed to by register RA) . If 
the event variable is active, the ERROR 
condition is raised - otherwise IHETEVA 
takes the following action: 

1. It informs (POSTS) the control task it 
wishes to execute soft code and then 
waits until the request is satisfied. 

2. It sets the I/O flag in the event 
variable (bit 1 of the flag byte) to 
zero. 

3. (a) If the bit string = * O'B, it sets 

bit 1 (the •complete* bit) of the 
EC3 in the event variable to zero. 

(b) If the bit string = • l^B, it tests 
to see whether the event is 
already complete. If not complete 
it posts the ECB with a completion 



4. 



code of zero. If it is complete, 
IHETEVA does nothing. 

It informs the control task it has 
finished executing soft code (Code = 0) 



PRIORITY PSEUDO-VARIABLE 



The PRIORITY pseudo-variable is used to set 
the dispatching priority of a task to a new 
value relative to that of the current task. 
On execution of an assignment statement in 
which the PRIORITY pseudo- variable appears, 
the expression on the right-hand side is 
evaluated and converted to a fixed-point 
binary constant of default precision, which 
is assigned to a fullword. Compiled code 
then calls IHETPRA, passing the address of 
the task variable of the task named in the 
pseudo-variable and that of the fullword 
(in a list pointed to by register RA) . If 
the pseudo- variable does not specify a 
task, the current task is assumed. IHETPRA 
requests the control task to change the 
priority of a task by posting a code of 08 
in the PECB of the specified subtask. The 
control task branches to IHETPRB which uses 
the dispatching priority of the task 
variable to compute the new priority. 
IHETPRB then stores the new priority value 
in the task variable; if the task variable 
is already active, it issues a CHAP (change 
priority) macro to change the priority of 
the associated task. It then assigns to 
the task variable the new value of the 
dispatching priority, calculated as 
follows : 

New dispatching priority of named task 
= MAX (0,MIN (limit-l,P+N)) 

where P = dispatching priority of 
current task and N = increment 

NOTE: Under this system of changing 
priorities, any task can change the 
priority of any other task. 



PRIORITY BUILT-IN FUNCTION 



The PRIORITY built-in function yields the 
dispatching priority of a task relative to 
that of the current task. On execution of 
a statement in which the function appears, 
compiled code calls IHETPBA, passing the 
address of the task variable of the task 
named in the function and the address of a 
fullword target field (in a list pointed to 
by register RA) . IHETPBA subtracts the 
dispatching priority of the current task 
from that of the named task, and assigns 
the difference to the target field. The 
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dispatching priorities are obtained from 
the respective task variables. 



THE WAIT STATEMENT 



When a WAIT statement is executed in a 
multitasking environment, compiled code 
calls the library module IHETSW, passing 
the addresses of the event variables 
associated with the statement. IHETSW 
first places itself in any queue that may 
exist via control task subroutine ENQ so 
that the control task may decide when 
IHETSW may safely access "soft code". 

It then scans the event variables to see 
whether enough events to satisfy the WAIT 
statement are complete with regard to the 
PL/I program ('complete' bit, ECMP, set to 
1) . If not, IHETSW scans the ECBs for the 
I/O events, and in each case where the I/O 
event is complete sets the check bit (EMCH) 
in the corresponding event variable to '1*. 
A list is then made of all the incomplete 
I/O and multitasking events. 

If the number of PL/I and I/O complete 
events is sufficient to satisfy the WAIT 
statements, the relevant I/O transmit 
modules are invoked to complete the I/O 
events. (See 'General Logic and Flow' 
under "Record-Oriented I/O* in Chapter 3.) 
If there are no multitasking events in the 
list, and if the number of completed I/O 
events is not sufficient and all the I/O 
events must be completed to satisfy the 
WAIT statement, the check bit in each event 
variable is set to 1 and the relevant I/O 
transmit module is invoked. If not all the 
I/O events need to be waited on, or if 
there are some multitasking events in the 
list, a multiple WAIT instruction is issued 
for the list of incomplete events. When 
the macro has been satisfied, if the list 



included any I/O events, the corresponding 
ECBs are scanned and the check bits in the 
event variables corresponding to completed 
ECBs set to 1; the I/O transmit module is 
then invoked. 

The I/O event variables that are checked 
by the transmit modules are set complete 
and the check bits are set to zero. The 
event variables are then set inactive and 
removed from the task and file chains. 
IHETSW then dequeues from the control task 
by posting the CTECB with a completion code 
of zero. 



ALTERNATIVE I/O MODULES FOR MULTITASKING 
PROGRAMS 



Alternative multitasking and 
non-multitasking modules for input/output 
operations have been created in order to 
prevent the non-multitasking user from 
being inflicted with any multitaskiing 
overheads. These modules are: 



Non -multi t asking 



IHEOCL 
IHECLT 
IHEPRT 
IHEIOB 
IHEDDO 
IHEION 



Multitasking 

IHEOCT 
IHECTT 
IHEPTT 
IHEIBT 
IHEDDT 
IHEINT 



The entry points for the multitasking 
modules correspond with the entry points of 
the non-multitasking modules. Modules 
which have no alternative form will call 
the correct module by extracting its 
address from the list addressed by 
pseudo-register IHEQADC. This list is 
assembled into IHESAP or IHETSA, whichever 
is present. 
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CHAPTER 6: ERROR AND INTERRUPT HANDLI NG 



The PL/I Library handles two types of 
conditions at object time which cause 
interruption to the main flow of a program. 
These are: 

1. Conditions for which it is possible to 
specify an on-unit: 



There is an error message for each ON 
condition. In some cases the condition 
(e.g., CONVERSION) may have a group of 
errors associated with it and has therefore 
a group of messages. A complete list of 
the internal error codes and their 
associated messages is given in Appendix E. 



a. Computational program interrupts, 



b. Other conditions. 



PROGRAM INTERRUPTS 



2. Execution error conditions not covered 
by a PL/I-defined condition. 

If any of these conditions occurs, 
control is passed to the library error 
handling module IHEERR. (See Figure 29.) 
This module is always resident; if it is 
necessary to print a message at execution 
time, IHEERR links to a group of modules 
normally non-resident but brought into 
storage when reguired. These are: 

IHEESM: This loads one of the message 
modules and prints the 
appropriate message. 

IHEERD: Data processing error messages. 

IHEERE: Error messages other than those 
in the other error message 
modules . 

IHEERI: Input/output error messages. 

IHEERO: Error messages for non-I/O ON 
conditions. 

IHEERP: Error messages for I/O ON 
conditions . 

IHEERT: Multitasking error messages. 

The error messages and their associated 
ONCODES are described in IBM System/360 
Operating System: PL/I (F) Programmer's 
Guide . 

All the PL/I-specified ON conditions 
except I/O SIZE and I/O CONVERSION are 
raised by compiled code to facilitate 
reference by the error-handling 
subroutines. Each ON condition has a code 
number (internal to the library) consisting 
of two hexadecimal digits. When an ON 
condition is raised, the code associated 
with it is placed in the error- handling 
pseudo-register IHEQERR. 



Fifteen possible program interrupts can 
occur in System/360. Seven of these are, 
or may be, related to computational 
conditions in PL/I (see Figure 28) ; 
on-units may be specified for these 
conditions. Seven of the remaining eight 
are treated as errors of a non-ON type; the 
eighth one, significance is not handled. 



| Program Interrupts 
I" 



—i 



Fixed-point overflow 
Fixed-point divide 
Decimal overflow 
Decimal divide 
Exponent overflow 
Exponent underflow 
Floating-point divide 



| PL/I Conditions | 



| FIXEDOVERFLOW 

| ZERODIVIDE 

| FIXEDOVERFLOW 

| ZERODIVIDE 

| OVERFLOW 

J UNDERFLOW 

| ZERODIVIDE 



Figure 28. Program Interrupts and PL/I 
Conditions 

Because the user may specify on-units 
for handling certain PL/I conditions, when 
an interrupt occurs the PL/I program must 
gain control to see if there is an on-unit 
associated with that particular interrupt. 
This is achieved by the GET PRV subroutine 
in the IHESA module, which issues a SPIE 
macro to: 

1. Provide a program interrupt control 
area (PICA). This is a six- byte area 
(in IHESA) which contains the address 
to which control is passed when an 
interrupt occurs, and information on 
the type of interrupt handled by 
IHEERR. 

2. Cause the supervisor to create a 
program interrupt element (PIE). This 
is a 32-byte area which contains the 
PICA address and also a save area for 
the old PSW and registers 14 to 2 when 
an interrupt occurs. 
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Figure 29. Flow through the Error Handling Routine (IHEERR) 
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j Interrupt Mask | 

Figure 30. Format of the Program Interrupt 
Control Area (PICA) 

Definitions of PICA fields; 

PM: Program mask 

A (Exit subroutine): Address of the entry 

point in IHEERR to which control is to 
be passed when one of the specified 
interrupts occurs. This entry point 
is IHEERRA. 

Interrupt mask: Indicates to the supervisor 
which interrupts are to be handled by 
IHEERR. These interrupts are all the 
fifteen possible ones except 
significance. 



7 8 
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A (PICA) 



OPSW(Bits 0-31) 



OPSW(Bits 32-63) 
Register 14 



Register 15 



-H 



Register 



Register 1 
Register 2 



-H 






._j 



Figure 31. Format of the Program Interrupt 
Element (PIE) 

Definitions of PIE fields: 

A (PICA): Address of PICA, for supervisor 
use 

OPSW: Contents of the old program status 
word 

Registers 14 to 2: Contents of these 

registers when an interrupt 
occurs 

On entry to IHEERRA, register RA 
contains the address of PIE. 

It is possible for another program 
interrupt to occur before user corrective 
action has been completed. IHEERR has to 



guard against this eventuality when it 
obtains control, otherwise the second 
interrupt would cause the supervisor to 
terminate the task. To avoid this, the 
following method is used: 



1. The PSW in PIE (the old PSW) is saved 
in the LWE + x '7 0' area in library 
workspace. 



2. Bits 40 to 63 of the PSW in PIE are 
changed to contain the address of the 
appropriate entry point in IHEERR; 
control is returned to the supervisor. 

3. The supervisor assumes the interrupt 
has been handled satisfactorily and 
transfers control to the new address 
in the PSW in PIE? thus it enters 
module IHEERR again. 

Floating-point registers are saved in 
the library communication area, and the old 
PSW is inspected to find the cause of the 
interrupt. 

If a fixed-point or decimal overflow 
interrupt is forced to occur, the SIZE 
condition may be raised. Therefore when 
one of these interrupts occurs, the 
pseudo- register IHEQERR must be inspected 
to see if the SIZE code has been set. 
Similarly, if any of the divide interrupts 
occurs, IHEQERR must be inspected to see if 
the ZERODIVIDE code has been set. If it 
has, the condition is disabled and control 
returns to the point of interrupt. 

Certain very unusual circumstances may 
result in a program interrupt occurring 
during the execution of IHEERR or of one of 
the library modules called, or linked to, 
from it. For example, if the program 
destroys the PRV, or the DSA chain, or 
parts of library workspace, then it is 
likely that sooner or later a specification 
or addressing interrupt will occur. 

Under these circumstances, the 
programmer or systems engineer requires a 
dump at the earliest opportunity. To 
achieve this, and to prevent any attempt to 
re-enter IHEERRA on account of the second 
interrupt, a SPIE macro is issued every 
time IHEERR is entered. This macro 
provides that, in the event of an interrupt 
occurring, IHEERR shall be entered at entry 
point IHEERRE. Similarly, another SPIE 
macro is issued at each exit point, to 
restore IHEERRA as the normal entry point 
for program interrupts during the execution 
of compiled code and library routines. 

When IHEERRE is entered, a message is 
printed on the console and the program is 
abnormally terminated, with a dump. 
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Figure 32. PL/I ON Conditions 



ON CONDITIONS 



The six classes of ON conditions defined in 
PL/I are shown in Figure 32. To deal 
satisfactorily with the situation when any 
of these conditions arise, IHEERR must: 

1. Recognize the condition. 

2. See if it is enabled. 

3. If so, see if there is an on- unit for 
the condition. 

4. If there is an on-unit, transfer 
control to IHESARA, which, after doing 
the necessary housekeeping, will 
transfer control to the on-unit. 

5. If no on-unit, take system action for 
the condition. 

6. Return to the interrupted program or 
terminate, according to the provisions 
of the PL/I language. 



In order to carry out these operations 
IHEERR needs: 

1. Information passed when the error 
condition arises. 

2. Information set by compiled code in 
the DSA for each procedure. A 
two-word ON field is allocated in the 
DSA for this purpose. (See Chapter 
4.) 



Action b y Compiled C ode 



Action taken by compiled code in 
preparation for the possibility of a 
condition arising during execution is 
summarized here. 

Prologue: The prologue allocates space in 
the DSA for: 

1. Every ON statement in the block. 

2. Each ON condition disabled in the 
block. 

ON CHECK (identifier 1, identifier n) 

is interpreted as n ON statements. 

For each of the occurrences given above, 
the prologue stores information in the two 
words in the DSA ON field: 

1st word : Contains the error code for the 
condition and the address of data 
identifying the condition. This word 
is called the search word comparator . 
(See Figure 33.) 



j Type of ON 
| condition 



h 



1/0 



■T 1 

| Contents of word | 
j. T < 

j Byte lj Bytes 2 to 4 j 

1 



CONDITION 



H 



I 

j CHECK (label) | 



| A (DCLCB) 

V ^ 

| j A (CSECT) j 

\ Error (• -j 

| A (Symbol name 6 | 
| | code | length) | 
JCHECK (variable) | |A (Symbol table) | 
j. 1 f 4 

| Others | | Nothing stored | 
l x x J 

Figure 33. Format of the Search Word 
Comparator 



2nd Word : Byte 1: Bits 0, 1 and 4 are set 
as follows: 

Bit 0=0 Not the last ON field in the 
DSA 



= 1 Last ON field in the DSA 
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Bit 1=1 Condition disabled 

Bit 4=1 Dummy ON field 

In the second word, either bit 1 or bit 4 
is set to 1. (See 'Prefix Options', 
below.) 

ON Statement: When the ON statement is 
executed, compiled code stores information 
in the second word of the ON field: 

Byte 1: 

Bit 2=0 SNAP not required 
= 1 SNAP required 

Bit 3=0 Normal 

= 1 System action required 

Bit 4 = No longer dummy 

Bytes 2-4: A(on-unit) 

Prefix options: An ON field for an ON 
condition must be created by the prologue 
whenever : 

1. An ON statement is present in the 
block. 

2. An ON condition becomes disabled at 
any time during the execution of the 
block. 

3. CHECK is enabled within the block. 

This ON field is always set to dummy by the 
prologue. It is also set to disabled if: 

1. The condition is disabled by a prefix 
option in the block-header statement. 

2. The condition is disabled by default 
and there is no enabling prefix option 
in the block- header statement, or 
within the block. The exceptions to 
this are CHECK, SIZE, STRINGRANGE, and 
SUBSCRIPTRANGE, which are dealt with 
as follows: 

CHECK: No ON fields are created if 
this condition is disabled by 
default 

SIZE, STRINGRANGE, and SUBSCRIPTRANGE: 
If these conditions are disabled 
by default, flags are set in the 
flag byte of the DSA as follows: 



SIZE: 

STRINGRANGE 

SUBSCRIPTRANGE: 



bit 7 = 
bit 2=0 
bit 4=0 



Execution of an ON statement in the block 
causes removal of the dummy flag and 
insertion of the flags indicating the 
action required. It does not remove the 



disable flag if on. Execution of a REVERT 
statement causes reinstatement of the dummy 
flag. 

During execution of the block, statements 
may be executed which have disabling prefix 
options in them. Compiled code must be 
inserted before and after the statements 
to: 

1. Set the disable flag before the 
statement. 

2. Restore the original flags after the 
statement. 

Similarly, to enable prefix options, 
compiled code must: 

1. Set the disable flag off before the 
statement . 

2. Restore the original flags after the 
statement. 



Prefix options specified on outer blocks 
carry down into internal blocks. The 
implementation of these blocks should be as 
if the option had been explicit in each of 
them. 



Action by the Library 

When an ON condition arises during 
execution, IHEERR gains control from one of 
the following: 

1. The supervisor 

2. Compiled code 

3. Another library module 



In case 1, the ON condition code 
required is determined by inspection of the 
program interrupt code in the old PSW. For 
cases 2 and 3, the ON condition code is 
passed in pseudo-register IHEQERR, except 
for the CHECK and CONDITION conditions, 
when a parameter list is used. From this 
code and information passed in the calling 
sequence, a search wor d is generated in 
library workspace in all three cases; the 
format of the search word is identical with 
that of the search word comparator 
(Figure 33). 

When the search word has been created, 
IHEERR initiates a search through the chain 
of DSAs to determine the action to be 
taken. Each DSA is analyzed in turn, from 
the end of the chain upwards towards the 
beginning. The search proceeds as follows: 
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1. Bit 6 of the flag byte of the first 
available DSA is tested to see if that 
DSA contains any ON fields. Then: 

a. No ON fields ; If the DSA is the 
current DSA and the condition is 

SIZE, STRINGRANGE, or 
SUBSCRIPTRANGE, the flag byte of 
this DSA is examined to see if the 
condition is disabled: 

Disabled : the program returns to 
the point of interrupt. 

Not disabled : The DSA is ignored. 

If the condition is CHECK, the 
program returns to the point of 
interrupt. 

b. ON fields : The first word of each 
ON field - the search word 
comparator - is compared with the 
search word to see if a match is 
found. If a match is found, the 
second word of the ON field in the 
DSA is tested to see what action is 
required. 

2. If the last ON field is reached before 
finding a match, then: 

a. If the DSA is the current DSA and 
the condition is SIZE, STRINGRANGE, 
or SUBSCRIPTRANGE, the 
corresponding flags in the DSA are 
tested. 

b. The error code is tested to see if 
the condition is CHECK. 

This may result in a return to the point 
of interrupt. If not, the next DSA is 
obtained and analyzed in the same way. 

If a match has been found, then the 
following tests are made: 

1. Is the condition disabled by a prefix 
option? (This test can only be 
applied when the matching ON field is 
contained in the current DSA. ) 

Disabled : No further processing 
in IHEERR; the program returns to 
the point of interrupt. 

Not disabled : Next test is made. 

2. Is the matching ON field a dummy ON 
field? 

Dummy ON field : The field is 
ignored and the next DSA is 
obtained. 



No dummy ON field : 
made. 



Next test is 



3. Is SNAP action required? 

SNAP action r equired : A summary 
flow trace is written on the 
system output file. This output 
contains the ON-condition 
abbreviation and trace- back 
information identifying the 
procedures in the chain. The 
statement number may optionally 
be included. Each procedure is 
identified by chaining back 
through the DSA chain until a 
procedure DSA is found and then 
using the contents of register BR 
in the appropriate save area. 
The search ends when the 
chain-back reaches the external 
save area. An example of this 
output is given in IBM System/360 
Operating System: PL/I (F) 
Programmer's Gui de. 

SNAP action not required : Proceed 
normally. 

In a multitasking program, when the 
search word has been created, IHEERR calls 
IHETER, which searches the ON fields of the 
DSA in a similar manner to IHEERR. In the 
absence of a matching ON field, the search 
continues until the PRV VDA of the major 
task is reached. If a subtask PRV VDA is 
encountered during the search, any ON 
fields that have been copied into it from 
the DSA of the attaching task are also 
checked. If a match is not found, the 
search continues through the DSAs of the 
attaching task. 



System Action 



System action means writing a message and 
then either continuing or raising the ERROR 
condition. It is performed if: 

1. the system action flag is set in the 
matching ON field, or 

2. no matching ON field can be found in 
the DSA chain. 

If a match is found, and an on- unit 
address is given, then, to guard against 
the possibility of recursive use when 
control returns from the on-unit by means 
of a GO TO statement, a new block of 
library workspace is obtained. This LWS is 
added to the DSA chain as described in 
•PL/I Object Program Management*. In order 
to pass control to the on-unit, the 
| recursion subroutine in IHESAP is called; 
this establishes the correct environment 
and then branches to the on-unit. Return 
from the on-unit may be made in one of two 
ways: 
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1. On normal completion, control passes 
to IHEERR, which returns to compiled 
code at the point following the 
instruction which caused the condition 
to be raised. 

2. Execution of a GO TO statement. In 
this case the GO TO subroutine 
(IHESAFC or IHETSAG) is entered to 
carry out the housekeeping described 
in Chapters 4 and 5. 



An action indicator is obtained during the 
process to determine whether normal 
processing should continue if the ERROR 
condition is raised. The appropriate 
action is taken when the message has been 
printed as output. 



BUILT-IN FUNCTIONS 



STANDARD SYSTEM ACTION AND CONDITIONS OTHER 
THAN ON CONDITIONS 



If an ON condition is raised and there is 
no matching ON field for the condition, 
standard system action is taken. This 
action is defined by the PL/I language. 
Another set of error conditions can arise 
at object time for which no specific ON 
condition is defined in the language (e.g., 
logarithm of a negative number) . In these 
cases, implementation-defined system action 
is taken. 

An error message is printed when 
PL/I-defined or implementation-defined 
system action occurs. Then, depending on 
the severity of the condition, either 
processing continues or the ERROR condition 
is raised. In a non-multitasking program, 
or in a major task, raising the ERROR 
condition generally leads to the FINISH 
condition being raised and then to the 
abnormal termination of the job step by the 
ABEND macro. The exceptions to this are 
when there is a GO TO statement in the 
ERROR or FINISH unit. In a multitasking 
program, if the ERROR condition is raised 
in a subtask, instead of the FINISH 
condition being raised, IHETSAZ is invoked. 
(See ' Termination of a Task* in Chapter 5.) 
A complete list of object-time error 
messages, with details of the conditions 
that cause them to be issued, is given in 
IBM System/360 Operating System; PL/I (F) 
Programmer's Guide . 

when the printing of an error message is 
required, the appropriate modules of the 
non-resident part of the error package are 
dynamically loaded into storage. The seven 
modules concerned are: 

IHEERD, IHEERE, IHEERI, IHEERO, IHEERP, 
IHEERT: The error message modules; 
they contain the error message texts 
together with tables to locate the 
messages. Only the module containing 
the required message is loaded. 

IHEESM: Contains the code required to 

print SNAP and system action messages. 
This module is always required. 



The two built-in functions, ONLOC and 
ONCODE, may only be used in an on- unit; 
they provide environmental information 
associated with the raising of the latest 
ON condition. 



ONLOC 



An interrupt can occur that can cause entry 
to the on- unit in which ONLOC is specified. 
If this happens, the ONLOC built-in 
function identifies the BCD name of the 
entry point of the procedure in which the 
interrupt occurs. 

The address of this BCD name is computed 
by chaining back through the DSA chain 
until the first procedure DSA is reached 
and by using the contents of BR in the 
appropriate save area. The length of this 
name and the maximum length are found; 
these two lengths and the pointer to the 
BCD name are inserted in the target SDV 
whose address has been passed to ONLOC as a 
parameter. 

If ONLOC is specified outside an 
on-unit, a null string is inserted in the 
target SDV. 



ONCODE 



The ONCODE built-in function picks up a 
value from the WONC field in the library 
communication area in LWS previously set by 
IHEERR. This value is implementation- 
defined by the type of error that caused 
the interruption. It may be specified in 
any on-unit. If specified in an ERROR or 
FINISH unit, the ONCODE will be that of the 
error or condition that caused the ERROR or 
FINISH unit to be entered. 

If ONCODE is specified outside an 
on-unit, a unique ONCODE value (0) is 
returned. A list of ONCODEs and an 
explanation of their use are given in IBM 
System/360 Operating System; PL/KF) 
Programmer's Guide . 
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MODEL 91 AND MODEL 195 INTERRUPT HANDLING 



Program interrupts occurring in code 
executed on an IBM System/ 360 Model 91 or 
Model 195 require different treatment from 
that described above. This is necessary 
because Models 91 and 195 are capable of 
executing several instructions 
concurrently: hence a situation may arise 
in which several program exceptions may 
occur before an interrupt is raised. 



As soon as a single exception occurs. 
Models 91 and 195 ensure that execution of 
the instructions already decoded is 
completed, and then raise an interrupt. 
During execution of these instructions, 
further exceptions may occur. If there are 
no more instructions to be executed at the 
time an exception occurred, then the 
interrupt raised is known as a precise 
interrupt ; the PSW contains the address of 
the instruction following that in which the 
exception occurred. 



2. 



Identification of the type or types of 
exception in the interrupt: For Model 
91 bits 16-25, and for Model 195 bits 
16-27 excluding bit 18 are set as 
follows: 



Bit 

16 

17 

18 

19 

20 

21 V 

22 

23 

24 

25J 

26 

27 



Type of Exception 

} Model Protection 
195 Addressing 

Specification 
Data 

Fixed-point overflow 
Model kModel Fixed- point divide 
91 I 195 Exponent overflow 
Exponent underflow 
Significance 
Floating-point divide 
Decimal overflow 
Decimal divide 



Implementa tion 



If, however, further instructions were 
executed, then the interrupt is known as an 
imprecise interrupt ; the PSW at 
interrupt- time contains the address of the 
next instruction to be executed, but this 
is not necessarily the address of the 
instruction following any of the exceptions 
raised. The instructions causing the 
exceptions cannot therefore be identified. 
If there is more than one exception prior 
to interrupt, then a multiple-exception 
imprecise interrupt is said to have 
occurred. Full details of Model 91 and 
Model 195 operation and interrupt handling 
are given in IBM System/ 360 Model 91. 
Functional Characteristics . Form A22-6907, 
and IBM System/360 Model 195. Functional 
Characteristics . Form A22-6943. 



When an imprecise interrupt is raised, 

therefore. Models 91 and 195 indicate the 

situation by setting the interruption code 

and the interruption length code in the PSW 
as follows: 



Recognition that an imprecise 
interrupt has occurred: Bits 26-33 are 
set to zero for Model 91 and bits 
28-33 are set to zero for Model 195. 



The Library module IHEM91 handles the 
problems associated with imprecise 
interrupts on Models 91 and 195. This 
module is obtained by the user specifying 
the OBJIN option as a parameter in the EXEC 
statement; this creates an ESD entry that 
results in IHEM91 being linkage- edited with 
the Library error and interrupt module 
IHEERR. 

Initially, IHEERR tests bits 28-31 of 
the PSW to determine if these bits are all 
zero (i.e., if an imprecise interrupt 
exists) : 

1. All zero: Imprecise interrupt; control 
is passed to IHEM91 

2. Any bit non-zero: No imprecise 
interrupt; IHEERR handles the 
situation in the normal way 

On receiving control, IHEM91 tests bits 
16-27 excluding bit 21 to determine which 
exceptions have occurred. All bits (except 
significance) are tested, as more than one 
type of exception can occur in an imprecise 
interrupt. If the bit tested is on 
(non-zero), then: 

1. Condition list: IHEM91 sets an entry 
in a list of PL/I conditions and 
program exceptions. The list is 
stored in the LWE area of Library 
workspace (LWS) ; an entry indicates 
that the particular condition or 
exception must be raised. The list 
consists of from one to eight entries, 
processed in the order: 
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UNDERFLOW 

PIXEDOVERFLOW or SIZE 
OVERFLOW 
ZERODIVIDE 
Data exception 
Specification exception 
Addressing exception 
Protection exception 



information indicating the nature 
of these unprocessed entries is 
given. However, the ONCOUNT 
built-in function, when used in an 
ON unit, will return the number of 
entries remaining unprocessed. 



f stem action: 



Note; ZERODIVIDE is entered only once 
in the list, even if 
floating-point divide and 
fixed-point divide both occur. 
ZERODIVIDE will be raised on 
Model 195 if decimal divide 
occurs. Hence three exceptions 
may result in one ZERODIVIDE on 
Model 195. Significance is not 
handled, as it is disabled in 
all PL/I programs. 
FIXEDOVERFLOW and SIZE cannot 
both be raised since they are 
raised by the same hardware 
condition. FIXEDOVERFLOW may be 
raised by fixed-point overflow 
and decimal overflow on Model 
195. 

2. Interrupt count; The value in the 

ONCOUNT field (WONC ♦ «») in the LCA is 
incremented by 1. Thus the total 
value in this field is the total 
n timber of conditions or exceptions to 
be raised. When a multiple-exception 
imprecise interrupt does not exist 
(because there are no exceptions or 
only a single exception) the value in 
the ONCOUNT field is zero. 

IHEM91 then returns control to IHEERR in 
order that each condition in the list can 
be raised. As described above, a condition 
can be handled in one of two ways: 

1. By entering an ON-unit, with exit by 
either: 

a. A normal return 

b. A GO TO statement 

2. By system action 

These rules have to be considerably 
extended for handling a multiple-exception 
imprecise interrupt: 

!• ON unit for UNDERFLOW. FIXEDOVERFLOW. 
SIZE. OVERFLOW or ZERODIVIDE: 

a. Normal return : Next entry in the 
list is processed. If there are 
no more entries to be processed, 
then a return is made to the 
address in the PSW. 

b. GO TO statement : No more entries 
in the list are processed, and no 



a. For UNDERFLOW : When the error 
message has been printed, the next 
entry in the list is processed. 

b. For FIXEDOVERFLOW. SIZE. OVERFLOW, 
or ZERODIVIDE : No further entries 
in the list are processed. If the 
program terminates as an immediate 
result of system action, messages 
are printed to indicate the nature 
of the unprocessed entries. 

3. ERROR raised for a data. 

specification, addressing or 
protection excep tion: No further 
entries in the list are processed. If 
the program terminates as an immediate 
result of the system action, messages 
are printed to indicate the nature of 
the unprocessed entries. 

In order to implement these rules, 
IHEERR tests for a multiple- except ion 
imprecise interrupt after: 

1. Return from an ON uni t: If a 
multiple-exception imprecise interrupt 
exists, IHEM91 is entered at a second 
entry point in order to: 

a. Process the next entry 

b. Reduce the ONCOUNT value by one 

c. Return to IHEERR 

2. Program termination caused by ERROR 
condition: If a multiple- exception 
imprecise interrupt exits, IHEM91 is 
entered at a third entry point. The 
condition list is processed in order 
to print out a message for each entry 
not handled at the time the program 
terminated. Program termination is 
completed when the list is exhausted. 

ONCOUNT Built-in Function 

The ONCOUNT built-in function returns a 
non-zero value only when this function is 
used in an ON unit entered as a result of a 
multiple-exception imprecise interrupt in a 
Model 91 or 195. In such a situation, the 
binary integer returned is the number of 
entries that remain unprocessed (including 
the current one) at the time the ONCQUNT 
function is used. 
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Flush Instructions 

A program may not operate correctly on 
Model 91 or 195 if it requires 
identification of the instruction causing 
an imprecise interrupt. Similarly, it may 
not operate correctly if it requires that 
an imprecise interrupt is honored before 
some instruction later in the program is 
executed. However, the unwanted effects of 
imprecise interrupts can usually be 
eliminated by placing 'flush* instructions 
at certain points in the program. A 
•flush* instruction is an Assembler 
Language instruction of the form: 

BCR x,0 

where x is not equal to zero. An 
instruction of this type is a no-operation 
instruction for all of System/360, but it 
is implemented in the Models 91 and 195 in 
such a way that its execution is delayed 
until all previously decoded instructions 
have been executed. 

If the OBJIN compiler option is 
specified, flush instructions are generated 
by the compiler at the following points in 
the program: 

1. Before every ON statement 

2. Before every REVERT statement 

3. Before code to set the SIZE condition 

4. For every null statement 

5. Before code to change prefix options. 

If both the OBJIN and the STMT options are 
specified, the compiler generates a flush 
instruction to precede every statement in 
the program. 



replaced by "NEAR OFFSET... ", since in 
these circumstances the instruction causing 
the interrupt cannot be precisely 
identified. 



After a multiple-exception imprecise 
interrupt on a Model 91 or 195, certain 
exceptions will remain unprocessed if the 
ERROR condition is raised before all the 
exceptions have been handled. If the 
program subsequently terminates as a direct 
result of the ERROR condition being raised 
in these circumstances, one or more of the 
following messages will be printed out. 



IHE810I PROTECTION EXCEPTION 
UNPROCESSED AFTER 
MULTIPLE-EXCEPTION 
IMPRECISE INTERRUPT 



IHE811I ADDRESSING EXCEPTION 
UNPROCESSED AFTER 
MULTIPLE-EXCEPTION 
IMPRECISE INTERRUPT 



IHE812I SPECIFICATION EXCEPTION 
UNPROCESSED AFTER 
MULTIPLE- EXCEPTION 
IMPRECISE INTERRUPT 



IHE813I DATA EXCEPTION UNPROCESSED 
AFTER MULTIPLE-EXCEPTION 
IMPRECISE INTERRUPT 



Model 91 and Model 195 Object-Time 
Diagnostic Messages 



IHE81UI ZERODIVIDE UNPROCESSED 

AFTER MULTIPLE-EXCEPTION 
IMPRECISE INTERRUPT 



If object-time diagnostic messages are 
issued as a result of an imprecise 
interrupt, the words "AT OFFSET..." are 



IHE815I OVERFLOW UNPROCESSED AFTER 
MULTIPLE- EXCEPTION 
IMPRECISE INTERRUPT 
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CHAPTER 7 : MISCELLANEOUS CONTROL PROGRAM INTERFACES 



One function of the PL/I Library is to 
provide a standard interface with the 
control program which can be utilized by 
compiled code. Detailed implementation is 
described in Chapters 3, 4, and 5. The 
implementation described here concerns 
support for PL/I language statements and 
functions with a control program interface 
that does not fall into one of the 
categories discussed in those chapters. 
These are the PL/ I statements DISPLAY, 
DELAY, STOP and EXIT, and the built-in 
functions TIME and DATE. 



Full and Minimum Control Systems 



The full control system of IBM System/360 
Operating System will enable the PL/I 
Library to issue macro instructions which 
support the above-mentioned statements and 
functions. The relationship is as follows; 



PL/ 1 

DELAY 

TIME 

DATE 

DISPLAY 



Macro instruction 

STIMER(WAIT) 

TIME 

TIME 

WTO, WTOR (WAIT) 



Thus, the library support for language 
features is as follows: 

DELAY: The execution of the current task 
is suspended for the required time. 

EXIT and STOP: Both these statements raise 
the FINISH condition and then cause 
normal termination of the PL/I program. 

TIME: The time of day is returned to 

the caller in the form HHMMSStht where: 

HH = hours ( 24-hour clock) 
MM = minutes 
SS = seconds 
tht = tenths, hundredths and 
thousandths of a second 



DATE: The date is returned to 

the caller in the form YYMMDD where: 

YY = year 
MM = month 
DD = day 



DISPLAY: A message may be written on the 
console with no interruption in 
execution or, if a reply is expected, 
execution is suspended until the 
operator's reply is received. If the 
EVENT option is used when a reply is 
expected, execution is continued 
without interruption until a 
corresponding WAIT statement is 
encountered; execution is then 
suspended until a reply is received. 



The multiple console support (MCS) 
feature is supported for PL/I usage by 
means of the ROUTCDE and DESC (route code 
and message descriptor) parameters of the 
WTO macro instruction. This feature allows 
the use of one Master Console and up to 31 
secondary consoles. The values provided 
for ROUTCDE and DESC, in PL/I are: 



DISPLAY 



DISPLAY WITH REPLY 



ROUTCDE = 2 
DESC = 7 



ROUTCDE = 1 
DESC = 7 



ERROR MESSAGES (if SYSPRINT not available) 

ROUTCDE = 11 
DESC = 7 



The minimum control system does not 
support the TIME and STIMER macro 
instructions. Use of the DELAY statement, 
and TIME and DATE built-in functions will 
result in the ERROR conditions being 
raised. 
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CHAPTER 8: DATA PROCESSING ROUTINES 



I/O EDITING AND DATA CONVERSION 



PL/I allows the user a wide choice in 
selecting the representation for his data, 
both on the external medium and internally 
in storage; considerable flexibility is 
permitted in specifying changes of data 
type and form. The library conversion 
package is designed to implement the full 
set of editing and conversion functions. 
To avoid unnecessary duplication of code, 
standard intermediate forms are used. This 
has the effect of reducing the number of 
library modules in the package to about 
fifty, to cover about two hundred logical 
conversions. To speed up processing, 
direct routines are provided for some of 
the most frequently used conversions, while 
the compiler generates in-line code for 
some of the simpler ones. 

To restrict further the storage 
requirements for the library conversion 
package, the F level compiler analyses the 
actual changes of data required for a 
particular execution. Sometimes these are 
not fully known at compile time, and then a 
worst case has to be taken. From this 
information, by use of the linkage editor 
LIBRARY statement and external references 
within the compiled modules, the loading of 
conversion modules is limited to those 
known to be required. This technique can 
be of considerable value, especially when 
only a small number of data types is used 
by the source programmer. Further details 
are provided in IBM System/360 Operating 
System: PL/I (F) Compiler, Program Logic 
Manual. 

With one exception, all the modules 
contained within the library conversion 
package are called by means of the PL/ I 
standard calling sequence (described in 
'Linkage Conventions*, Chapter 2). The 
exception is IHEVCS (complex-to-string 
director) which is called by the operating 
system external standard calling sequence. 

The letters in the module name indicate 
the module usage; see Figure 34. 



STRUCTURE OF LIBRARY CONVERSION PACKAGE 



To perform a change from a source data item 
to a target data item may involve a 
succession of steps and the use of several 
individual library modules within the 



package. The structure of the library 
conversion package is shown in Figure 36. 

In association with each individual 
step, the attributes of the source or the 
target fields, or of both, must be known. 
The required information is provided in the 
calling sequences. Each data item has a 
corresponding format element descriptor 
(FED) or data element descriptor (DED). 
With one exception, the formats of these 
control blocks are described in Appendix H. 
The exception is that of a DED generated at 
object time for communication between 
library modules. (See Figure 35.) 



Letters 
1 2 3 4 5 6 



H 



H E K 



H E V P 



H E V Q 



h" 



Meaning 



Director 



Picture check 



Conversion involving 
packed-decimal 
intermediate, except 
IHEVPG and IHEVPH 



H 



I 


H 


E 


V 


F 


__ + 

| Conversion involving 
I floating-point 
j intermediate 

_X— — — — — -.____— _______ 


I 


H 


E 


V 


K 


~T 

| Conversion involving 
j numeric fields 
x — — — 


I 


H 


E 


V 


S 


— t — 

| Conversion involving 
j strings 

_- X 



H 



+-- 



Conversion involving 
external character 
data being converted 
to type string 



H 



u 



■+- 



Direct conversion to 
improve performance 



■H 



-H 



| Mode conversions 

i x j 

Figure 34. Module Usage indicated by 
Letters of Module Name 

This DED is created when it is necessary 
to convert a character representation of an 
arithmetic value to an intermediate coded 
arithmetic data type, prior to conversion 
to a string target. The form of this DED 
is the same as that for a coded arithmetic 
data item (CAD) , and consists of a flag 
byte and precision bytes representing the 
quantities p and q. As for coded data, the 
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I 

j Code 

I- 

I 

I = 



Bit 



| Non- | | 

j sterling! Short j 



I I I 

| Decimal | Fixed | Real 



= 1 



| Sterling | Long 
.x j. 



| Binary | Float | Complex | 
i x j. J 



Note: Bits 0, 1 and 4 are always 1. The hexadecimal • 10' superimposed on the DED flag 
byte indicates the presence of a halfword fixed point binary variable. Bit 3 is 
set to 1 and bit 6 is set to 0. 

Figure 35. DED Flag Byte for Character Representation of an Arithmetic Data Item 



flag byte defines the attributes of the 
corresponding data item; bit 1 is set to 1 
to indicate that a character representation 
of an arithmetic value is referred to. 



Directors 



The structure chart makes frequent 
reference to * directors* . These modules 
are used to fulfil two main purposes: 

1. The matching of source element with 
target element, which may not be known 
at compile time. 

2. The controlling of the flow at object 
time by means of interpretative 
information passed to them. 

The latter function is best illustrated by 
the arithmetic conversion director 
CIHEDMA) , where a single call determines 
the flow through a sub-package of over 
twenty arithmetic conversion routines. 
(See below in • Arithmetic Conversions'.) 

There are director routines at four 
levels. (See Figure 36.) They are: 

1. Complex format directors. 

2. Input/output format directors and the 
complex-to- string director. 

3. String-to-arithmetic and 
arithmetic-to-string directors. 

4. Arithmetic conversion director. 

All directors except the complex-to- string 
director can be called directly from 
compiled code; the complex-to- string 
director is invoked from the complex format 
directors or from list/data- directed input 
only. 

Any director can call any below it in 
the structure. 



Edit-directed I/O 



Edit-directed transmission allows the user 
to specify the storage area to which data 
is to be assigned or from which data is to 
be transmitted and the actual form of the 
data on the external medium. The 
information concerning storage areas is 
specified in the source program by means of 
a data list, and the information about the 
form of the data on the external medium by 
means of a format list. 

The library conversion package is 
designed to implement the executable format 
scheme discussed in Chapter 3. This is 
done by the object time matching of list 
item and format item through the use of the 
director routines mentioned above. The set 
of I/O directors provided and their 
association with the PL/I data format items 
is shown in Figure 37. 



I/O EDITING 



Complex Directors: Complex format items on 
the external medium may have real and 
imaginary parts of differing attributes. 
When the list item and the target field are 
of type arithmetic, this situation is 
handled in the complex director by making 
consecutive calls for real and imaginary 
format items, and passing control to the 
particular format director associated with 
the format item. 

When the target field is a string, 
however, there are two problems with C 
format items. First, the data on the 
external medium must be scanned dynamically 
in order to deduce the attributes of the 
format item. The information derived from 
this is stored in a special DED. (See 
•Structure of Library Conversion Package*.) 
This DED is necessary for the conversion of 
all format items and constants. 
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j Compiled 
-•j code 



r— ^ 



<— 



Complex 

format 

director 



r t 

J Arithmetic | 
| conversion |<- 
| director j 

I 
I 
v 

r 1 

| Arithmetic | 
j conversion j 
j routines j 
i j 



1~ 



Complex- | 

to-string j 

director j 

,. j 



V 

r 1 

| String<-> | 
->| arithmetic |— 
j directors |~- 

I T J 

I 

< 

I 

V 

r 1 

| Mode j 

->| conversion j<- 

I routines j 

L ,. J 



| Data 
j analysis 
| routines 
l 



r 1 

| Input /Out put | 
-j format [ — 
| directors y-^ 

I T J 

I 
1 



— > 



V 

r 1 

| Decimal | 

j constant<-> j 

j arithmetic | 

L T J 

I < 



V 

r 1 

j Direct | 
| arithmetic j 
j conversion j 
l J 



LWS 
Level 

No. 



| Picture 
j checking 
j routines 

L 



I I 



String j 
routines | 



Note; <-> indicates a conversion in either direction 
Figure 36. Structure of the Conversion Package 



Second, the base, scale and precision of 
the real and imaginary parts have to be 
compared, to determine the highest set of 
attributes, so that the form of the 
converted data in the string target may be 
known. This is done by invoking a special 
director, called the complex-to-string 
director, which performs the necessary 
analysis on the DEDs of the real and 



imaginary parts of the C format item. Each 
item is then converted by the rules of type 
conversion to coded complex and then to 
string. 

Input/Output Directors ; The input /output 
directors named above Tother than C format) 
perform three major functions. Because 
there are slight differences between input 
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n 


_ — — _ T . 

PL/I | 

format item | 
Complex | 


Director 


_ T" 


_ 1 

Module name | 
„_„_ j 


h 


_ T __ — ^ 

Input | Output | 

IHEDIM | IHEDOM | 


C 




Fixed and j 
floating point j 


F/E 




IHEDIA | IHEDOA | 




Bit string j 


B 




IHEDID | IHEDOD | 




Character string j 


A 




IHEDIB | IHEDOB | 




Picture j 


P (DEC, STL) 
P(CHAR) 




IHEDIE | IHEDOE | 
IHEDIB | IHEDOB | 



Figure 37. Input/Output Directors for PL/I Format Items 







INPUT 






String value 


— T" 
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List item 


i 
1 


Conversion j 


Character string 
Bit string 
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1 

-+- 

1 

1 

1 
X- 


Arithmetic 
Character string 
Bit string 

Arithmetic 
Character string 
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1 

1 

1 

-+- 

1 

1 

1 
i 


Character to arithmetic j 
Character string assignment | 
Character to bit string | 

Bit string to arithmetic | 
Bit string to character string | 
Bit string assignment j 


Arithmetic 
(including 
expression) 


— T 

1 

1 

1 
i. 


Arithmetic 
Character string 
Bit string 


l 
1 

1 

1 
i 


Arithmetic type conversion j 
Arithmetic to character string j 
Arithmetic to bit string j 


OUTPUT | 


List item 


1 


String value 


1 

1 


Conversion j 


Arithmetic 


1 

1 


Character representation 
of data value 


1 

1 
i 


Arithmetic to character string j 


Bit string 


1 

1 
X. 


Bit string in character 
form 


1 

1 
i 


Bit to character j 


Character string 


1 


Character string 


1 


Character string assignment j 



Figure 38. Conversion for List/Data Directed I/O 



and output, the functions are described 
under these headings. 

Input; A call is made to IHEIOD to request 
w bytes and a data field pointer. If the w 
bytes can be obtained from the current 
buffer, the address returned to the input 
director is that of the data field in the 
buffer itself. If not, a VDA is obtained 
and the requisite field of w bytes is built 
up in the dynamic area. The VDA address is 
stored in WSDV in the LCA. 

These two conditions are normal. If, on 
the other hand, an abnormal return occurs 



at this point, this signifies that an 
ENDFILE condition exists and that a return 
has been made from an ENDFILE on-unit. In 
this case, the I/O director must return 
control to the code associated with the 
next PL/I source statement, which is 
pointed at by the second word of 
pseudo- register IHEQCFL. 



If there is no abnormal return, the 
target DED is inspected by the director 
routine and the first stage of the 
necessary conversion process is initiated 
by means of a suitable call to a routine 
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below the input director level, 
structure chart, Figure 36.) 



(See 



When the conversion has been completed 
and the data item assigned to the list 
item, the input director calls the I/O 
package again. At this stage, the I/O 
routine tests for the TRANSMIT condition, 
and, if necessary, calls IHEERR, to specify 
that the TRANSMIT condition is active, and 
that the format item transmitted is 
therefore suspect. In addition, any VDA 
that has been allocated is freed. 

Output : A call is made to the library I/O 
package to obtain an address for the 
external data item. If the w bytes 
specified can be satisfied within the 
current buffer, the address of the current 
buffer pointer is returned; if not, a VDA 
is obtained and the address of this dynamic 
storage is passed back. The source DED is 
then inspected and a call is made to the 
first subroutine in the conversion package 
to perform conversion. 

After assignment of the data item to a 
buffer area or VDA, a call to the 
appropriate I/O routine is made from the 
output director. If a VDA was used, the 
output field is split off into the 
appropriate buffers and the dynamic storage 
released. 

For both input and output, control is 
finally returned to compiled code. 



List- and Data-directed Input/Output 



The total set of conversions reguired by 
list/data-directed I/O is shown in Figure 
38. 

Since all the conversions represented 
deal with change of data from one internal 
representation to another, the conversion 
package is fully capable of performing the 
conversion for list/data-directed I/O. The 
type conversions are fully defined in the 
PL/I language and the modules that 
implement them are given below. Some 
examples of list/data-directed I/O are 
included in IBM System/ 3 60 Operating 
System; PL/I (F) Programmer's Guide . 



MODE CONVERSIONS 



Since data may be declared COMPLEX, and 
complex values may be written or read by 
list-directed and data-directed input and 
output, or by the C format item, two 
routines are provided to facilitate 



conversions of mode during I/O editing and 
during conversions between internal 
arithmetic and string data. 



TYPE CONVERSIONS 



Four director routines are provided to 
control the flow which enables changes 
between data of type string and data of 
type arithmetic, as required by the PL/I 
language. These routines are used by 
list-, edit- and data-directed I/O and in 
some internal conversions. 



TO: 



1 

I 
1 

String | 

T ^ 

Bit | Character | 



FROM: 

Arithmetic 

Bit string 

Character 
string 



Arithmetic! 



IHEDBN 
IHEDCN 



IHEDNB | IHEDNC 

I 



I I I 

I X J. X J 

Figure 39. Modules for Type Conversions 



STRING CONVERSIONS 



A set of generalized interpretive routines 
is provided to support the possible string 
conversions and assignments that may exist. 
Each module interrogates source and target 
information contained in the string dope 
vectors and DEDs in order to handle 
truncation, padding, and alignment for 
fixed and varying strings. Figure 40 shows 
the modules provided; it should be noted 
that there is no difference between a 
source character string with a picture and 
one without, as once the data has been 
checked into the source field, no further 
use is made of the picture. 



TO: | 

. T T 1 

| Character | Character with | 
| j picture 



Bit 



FROM: 
Bit 



I 



I 



H 



|IHEVSA| IHEVSB | 

I I I 
Character | IHEVSD j IHEVSC | 
x x x. 



IHEVSF 
IHEVSE 



..J 



Figure 40. Modules for String Conversions 
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ARITHMETIC CONVERSIONS 



implies radix change) . The two 
intermediate forms in use are: 



A direct routine IHEVQA converts 
floating-point data to fixed-point binary, 
in order to provide fast processing of this 
frequently used routine. Normally, 
however, all conversions (including this 
one) are dealt with by the library 
conversion package. 

This package carries out editing and 
conversions for all type arithmetic source 
fields which have type arithmetic target 
fields. It also handles conversions of 
format items and constants, which are 
character representations of arithmetic 
type data. The flow control through this 
subpackage is achieved by the arithmetic 
conversion director described below. 

The method employed is to use an 
intermediate form of representation 
according to the form of the source data 
and to relate this intermediate form to the 
target data, either by direct conversion or 
by use of a second intermediate form (which 



1. Packed decimal intermediate (PDI) 

This consists of 17 digits and a sign, 
together with a one-word scale factor 
(WSCF) in binary representing powers of 
ten. 

2. Long floating-point intermediate (FPI) 

This is the standard internal form, and 
consists of 14 hexadecimal digits. 

The logical flow through the package is 
shown in Figure 41. 

The arithmetic conversion director 
(IHEDMA) links together the modules 
required for a particular arithmetic 
conversion. It is called either directly 
by compiled code or by other director 
routines. The flag bytes in the source and 
target DEDs are interrogated to determine 
which modules are required for the current 
conversion and their order of execution. 
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| string j VPB 



| E format | VPE 

•-- >| character j< 

| string j VPC 



VFC 
VFE 



H Binary j < — ^ 
j constant j 
t j 



| Binary 
■> j fixed 
| data 
l 



<-H 



r 1 

| Floating- | 
■>| point |< — 
| data | 
l J 



r 1 

| Bit string | 

l > j constant j < — J 

VPH | | 

t J 



Note: The three- letter names, e.g., VKC, are the last three letters of the module name. A 
name above the flow lines indicates a conversion from left to right; a name below 
the line indicates a conversion from right to left. 

Figure 41. structure of the Arithmeric Conversion Package 
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The library communication area is used to 
record information required by successive 
modules as follows: 



WBRl Address of entry point of second 
module 



WBR2 Address of entry point of third 
module (if required) 



WRCD Target information 



The conversion director then passes 
control to the first module in the chain; 
the first transfers control to the second, 
and so on until the conversion is complete. 
The last module returns to the program 
which called the conversion director. All 
the modules which can be first in the chain 
set up by the conversion director use the 
source parameters passed to this director. 
The first conversion is always to the 
intermediate form of the same radix as the 
source. The results are stored in the 
following LCA fields: 

WINT Binary results 

WTNT Decimal results 
WSCF 

Three modules in the arithmetic package 
deal with data on the external medium. Two 
modules handle the output of F and E format 
items from packed decimal intermediate 
format, and the third provides conversion 
from F or E format items to packed decimal 
intermediate format. The LCA fields used 
for these modules are: 

WFED A (FED) at input 

WFDT A (FED) at Output 

WSWA Switches 
WSWC 

WOCH A (Error character): for ONCHAR 
built-in function 

WOFD Dope vector for ONSOURCE built-in 
function 



Edit Directed 



All data described by a picture is matched 
against the picture description. When a P 
format item is read in, this checking is 
performed by one of three picture check 
routines (decimal, sterling, and character) 
which is called by the appropriate input 
director. 

F/E format items are checked against the 
format element descriptor (FED). The 
validity of the characters in the data item 
is investigated prior to conversion to 
packed decimal intermediate format. 

If B format items are assigned in the 
target DED to a bit string, the items are 
checked in the character- to- bit module. 
Otherwise, a pre-scan within the B format 
input director checks that all characters 
in the string are either zero or one. 

If A format or B format is specified on 
input without a w specification, the 
compiled code calls IHEDIL (illegal-input 
format director) . This routine calls the 
execution error package, passing an error 
code. This causes a message to be printed 
and the ERROR condition to be raised. 



List/Data- Directed 



Within the conversion package, the 
constants which are converted to arithmetic 
are checked in the appropriate internal 
conversion modules. 

Decimal constants are converted by the 
F/E-to-PDI routine and are therefore 
checked by that routine as above. 

Binary constants are checked prior to 
conversion to floating-point intermediate. 

Bit string constants are checked prior 
to conversion to floating-point 
intermediate. 



Internal Conversions 



DATA CHECKING AND ERROR HANDLING 



Checking is carried out on data on the 
external medium for edit-, data- and list- 
directed input and on internal data items 
taking part in conversions. 



Checking of data is provided for the 
following: 

1. Character string to arithmetic. 

2. Character string to bit string. 

3. Character string to pictured character 
string. 
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4. Bit string to pictured character 
string. 



In cases 1 to 3 above, if an invalid 
character is found the CONVERSION condition 
is raised; in case 4, the ERROR condition 
is raised. 



When CONVERSION is raised, an error code 
is passed to IHEERR. The error code passed 
depends: 



1. On the type of operation (internal, 
I/O, or I/O with TRANSMIT condition 
raised) . 



Conversion 



F format 
E format 
B format 
Character string to 

arithmetic 
Character string to 

bit string 
Character string to 

pictured character string 
P format (decimal) 
P format (character) 
P format (sterling) 



Figure U2. Conversion Code Set in IHEQERR 




2. On the various formats and conversions 
involved. These consist of: 

F format 

E format 

B format 

Character string to arithmetic 

Character string to bit string 

Character string to pictured 

character string 
P format (decimal, character and 

sterling) 

Different ONCODE values are set for each, 
and may be interrogated in an on-unit 
provided for the CONVERSION condition. If 
the condition is associated with I/O, it is 
also possible that a TRANSMIT condition may 
be active. This can be tested in the 
on-unit for CONVERSION. A list of ONCODE 
values is given in IBM System/360 Operati ng 
System: PL/I (F ) Programmer's Guide . 

The conversion package routines set the 
following information before invoking the 
execution error package: 



WOFD 



WOCH 



Dope vector for field scanned 



Address of character in error 



IHEQERR Value of the error code. For 
I/O editing, a 1 bit is set in 
bit zero. 

Bits 12 to 15 are set according 
to the conversion being 
performed. (See Figure 42.) 

In addition to the occurrence 
of the CONVERSION error, the 
SIZE condition can also occur in 
the conversion package. Once 
again, a distinction is made 
between internal conversions and 
conversions involving the 
external medium. In the latter 
case, bit zero in IHEQERR is 
again set to one. 



In certain cases an illegal conversion 
may be requested or an invalid parameter 
may be passed to a conversion routine. In 
these cases the conversion package calls 
the error- handling subroutine, having set 
register RA to point to an error code. 
This causes a message to be printed which 
describes the error found; the 
error-handling subroutine then raises the 
ERROR condition. 

If a CONVERSION error occurs, the 
program can proceed in three ways: 

1. If system action is specified, a 
message will be printed and the ERROR 
condition raised. 

2. If CONVERSION is disabled, the 
conversion will continue, ignoring the 
character in error. 

3. If an on-unit exists, it will be 
entered. If the on-unit returns 
control to the conversion routines, 
they will assume that either the 
ONCHAR or ONSOURCE pseudo-variable has 
been used to correct or replace the 
character or field in error, and will 
automatically retry the conversion. 

Not e: If the pseudo-variables have not 
been used to correct the error, and if the 
on-unit attempts to return control to the 
conversion, a message will be printed and 
the ERROR condition raised. 



COMPUTATIONAL SUBROUTINES 



Computational subroutines within the PL/I 
Library supplement compiled code in the 
implementation of operators and functions 
within three main groups. These groups 
are: 
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1- Arithmetic evaluation 

2. Mathematical functions 

3. Array functions 

In addition to the description provided 
in this document, detailed information on 
algorithms and performance is published in 
IBM Svst em/360 Operating System: PL/I 
Subroutine Library: Computational 
Subroutines . 

A number of error and exceptional 
conditions not directly covered by 
PL/I-defined ON conditions may occur in 
these subroutines. In these cases, a 
diagnostic message is printed and the ERROR 
condition raised. By use of the ONCODE 
built-in function, the cause of interrupt 
may be ascertained in an ERROR unit and 
appropriate action may be taken. A list of 
the error messages and ONCODEs is given in 
IBM System/360 Operating System: PL/I (F) 
Programmer'* s Guide * 

When an aggregate of data items is being 
processed, the indexing through the 
aggregate is achieved by in-line code, as 
the library routines generally handle 
individual elements only. The array 
functions, however,, perform their own 
indexing, so that only a single call from 
compiled code is made. 

For modules handling data in coded form, 
character six of the module name indicates 
the type of data concerned; the meanings of 
this character are given in Figure 43. 



Character j 

Real or 
Real Complex Complex 







Binary 

Packed decimal 
Binary or 
packed decimal 
Short float 
Long float 



Figure 43 






G 
H 



Relationship of Data Form and 
Sixth Character of Module Name 



MATHEMATICAL FUNCTIONS 



The library provides subroutines to deal 
with all float arithmetic generic functions 
and has separate modules for short and long 
precision real arguments, and also for 
short and long precision complex arguments 
where these are admissible. 



Linkage to all mathematical subroutines 
is by means of the operating system 
standard. 

Where evaluation or conversion of an 
argument is necessary, this is done prior 
to the invocation of the library module. 
Hence, all arguments passed to the 
mathematical subroutines must be of scale 
FLOAT. As such, it is assumed that the 
arguments are normalized in aligned 
full word or doubleword fields for short or 
long precision respectively. The results 
returned are normalized similarly. 



Real Arguments 



j | Short 

| Function j float 

| SQRT | IHESQS 

j EXP | IHEEXS 

j LOG, L0G2.L0G 10 j IHELNS 

j SIN, COS,SIND,COSD j IHESNS 

j TAN, TAND | IHETNS 

j ATAN, ATAND j IHEATS 

j SINH, COSH j IHESHS 

j TANH j IHETHS 

j ATANH j IHEHTS 

j ERF, ERFC | IHEEFS 



Long | 
float | 

IHESQL | 
IHEEXL | 
IHELNL | 
IHESNL | 
IHETNL | 
IHEATL j 
IHESHL | 
IHETHL | 
IHEHTL j 
IHEEFL | 



j Complex Arguments 

Short 
| Function j float 



SQRT 

EXP 

LOG 

SIN, COS,, SINH„ COSH 

TAN, TANH 

ATAN, ATANH 






IHESQW 
IHEEXW 
IHELNW 
IHESNW 
IHETNW 
IHEATW 



Long j 

float | 

IHESQZ | 

IHEEXZ | 

IHELNZ | 

IHESNZ | 

IHETNZ | 

IHEATZ | 



Figure 44. Mathematical Functions 



ARITHMETIC OPERATIONS AND FUNCTIONS 



Library arithmetic modules provide support 
for all those arithmetic generic functions 
and operations for which the F level 
compiler neither generates in-line code nor 
(as for the functions FIXED, FLOAT, BINARY, 
and DECIMAL) uses the library conversion 
package. 

Linkage between compiled code and the 
arithmetic modules is established by means 
of the operating system standard for the 
functions supported and by means of the 
PL/I standard for the operators supported. 
The module description summaries provide 
information about linkage to individual 
modules. 
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Fixed- point data often require data 
element descriptors (DEDs) to be passed in 
order to convey information about precision 
(p # q) . Binary data is always assumed to 
be stored in a fullword correctly aligned, 
with < p < 31. Decimal data is always 
assumed to be packed in FLOOR (p/2) ♦ 1 
bytes, where < p < 15. Where such fields 
introduce high-order digits beyond the 
specified precision, these digits must not 
be significant. 



unnecessary object- time testing and enables 
a clear distinction to be made between SIZE 
and FIXEDOVERFLOW conditions. 

Floating-point arguments are assumed to 
be normalized in aligned fullword or 
doubleword fields for short or long 
precision respectively; the results 
returned are similarly normalized. 



In decimal routines, the target area is 
assumed to be of the correct size to 
accommodate the result precision as defined 
by the language. 



ARRAY FUNCTIONS 



Where assignment to a smaller field is 
required, the compiled code should generate 
an intermediate field for the result and 
subsequently make the assignment. This 
does not apply to ADD, MULTIPLY and DIVIDE 
with fixed-point decimal arguments, which 
perform the assignment themselves. Such 
action by compiled code avoids much 



The library provides support for compiled 
code in the implementation of the PL/I 
array built-in functions SUM, PROD, POLY, 
ALL, and ANY. Calls to array function 
modules are by means of the operating 
system standard; the indexing routines, 
which are used internally by the library, 
use the PL/I standard calling sequence. 



ARITHMETIC OPERATIONS 


Operation 


T 

| Binary 
J fixed 


1 

1 
i 


T 

Decimal | 
fixed j 


Short 
float 


T 
1 
1 


Long 
float 


Real Operations 


Integer exponentiation: 
General exponentiation: 
Shift-and-assign, Shift- 


x**n | IHEXIB 
x**y | - 

■and- load | 

_ j. 


i 

1 

1 

1 
i 


IHEXID | 

1 
IHEAPD j 
. j._ 


IHEXIS 
IHEXXS 


T 

1 

1 

1 
| 


IHEXIL 
IHEXXL 




Complex Operations 













Multiplication/division: Zi*z 2 , Za./z 2 | IHEMZU | IHEMZV | 
Multiplication: Zi*z a | - j - | 
Division: z^/Za I I | 
Integer exponentiation: z**n j IHEXIU j IHEXIV j 
General exponentiation: Zi**z 2 j j - j 
x x x. 



IHEMZW | IHEMZZ 
IHEDZW | IHEDZZ 
IHEXIW | IHEXIZ 
IHEXXW | IHEXXZ 
X 



ARITHMETIC FUNCTIONS 


Function | 
1 

_A 


Binary | Decimal | Short 
fixed j fixed j float 

J. _L 


1 

1 
i 


Long 
float 


Real Arguments 


MAX, MIN | 
ADD | 


IHEMXB | IHEMXD | IHEMXS 
| IHEADD | 


1 

1 
i 


IHEMXL 




Complex Arguments 







ADD | - | IHEADV | - | - 
MULTIPLY | IHEMPU j IHEMPV j j - 
DIVIDE | IHEDVU j IHEDW | - j - 
ABS j IHEABU j IHEABV j IHEABW j IHEABZ 
t L J X X — , J 

Figure 45. Arithmetic Operations and Functions 
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r t t 1 

| | Simple arrays, and | Interleaved string | 

| | interleaved arrays of | arrays with fixed- | 

j j variable- length strings | length elements j 

i. + + ^ 

| Indexers | IHEJXS j IHEJXI | 
| ALL, ANY j IHENL1 | IHENL2 j 

i x x J 

Note: IHEJXI is also used for indexing 

through interleaved arithmetic arrays 



PL/ 1 
functions 



Fixed - point 
arguments 



Floating-point arguments 



Short precision j 



Ti 



Long precision | 
H 



Simple |Interleaved| Simple j Interleaved) Simple | Interleaved! 



■+-- 



H 



SUM real 

Complex 

PROD real 

complex 

POLY real 

complex 



IHESSF 
IHESSX 

IHEPSF 
IHEPSX 



I— 



IHESMF 
IHESMX 

I HE PDF 
IHEPDX 



IHESSG 
IHESSG 

IHEPSS 
IHEPSW 



IHESMG 
IHESMG 

IHEPDS 
IHEPDW 



IHESSH 
IHESSH 

IHEPSL 
IHEPSZ 



IHESMH 
IHESMH 

IHEPDL 
IHEPDZ 



IHEYGF 
IHEYGX 



IHEYGS 
IHEYGW 



IHEYGL 
IHEYGZ 



Figure 46. Array Indexers and Functions 



In all cases, the source arguments are 
arrays and the function value returned is a 
scalar. The evaluation of this function 
value requires only one call from compiled 
code, indexing through the array being 
handled internally within the library. 



necessary conversion to bit string will be 
carried out before the library is invoked. 



STRING SUBROUTINES 



In the interests of efficiency, two sets 
of modules are provided: those which deal 
with arrays whose elements are stored 
contiguously (simple arrays) , and those 
which also deal with arrays whose elements 
are not in contiguous storage (interleaved 
arrays) . 

In order to deal with array element 
addressing, the library modules require an 
array dope vector (ADV or SADV) to be 
passed as an argument. The format of these 
dope vectors is described in Appendix H. 
The number n, the number of dimensions of 
the array, is required in addition to the 
ADV or SADV, and is passed as a separate 
argument. 

The PL/I language requires that the 
scalar values resulting from the use of the 
array functions, SUM, PROD, and POLY, 
should be floating-point, since the 
library modules are addressing each array 
element successively, the necessary calls 
to the conversion routines (to change scale 
from FIXED to FLOAT) are made from the SUM, 
PROD, and POLY modules which have 
fixed-point arguments. In the case of ALL 
and ANY functions, it is expected that any 



The library string package contains modules 
for handling both bit and character 
strings. Generally, individual modules 
handle a particular function or operation 
for bit or for character string; in the 
interests of efficiency however, additional 
modules are provided to deal with 
byte-aligned data for some of the bit 
string operations. 

The functions LENGTH and UNSPEC are 
handled directly by compiled code; support 
for BIT and CHAR is provided in the library 
conversion package. 

Linkage to the string subroutines is by 
means of the operating system standard for 
the functions SUBSTR, INDEX and BOOL, and 
by the PL/I standard for all others. The 
functions REPEAT, HIGH, and LOW use the 
PL/I standard as they are implemented as 
entry points to the concatenation and 
assign/fill routines. 

The address and the maximum and current 
lengths of a string are passed to library 
modules by means of string dope vectors. 
All string lengths supplied in SDVs are 
assumed to be valid non-negative values; 
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unpredictable results will ensue if this 
condition is not satisfied. 

Conversions (e.g. of decimal integers 
into binary integers for functions such as 
REPEAT) and evaluation of expressions are 
handled by the compiler, which is also 
responsible for recognising instances of 
byte-alignment which are suitable for the 
byte-aligned bit functions provided. 

The general design of the string package 
is influenced by the concept that complete 
evaluation of the right-hand side of an 
assignment statement occurs before the 
assignment. In this evaluation, there is 
usually an intermediate stage in which a 
partial result is placed in a field acting 
as a temporary result field. This does not 
prevent the compiler from optimizing by 



providing the actual target field of the 
assignment as the temporary result field, 
subject to the following conditions: 

1. If the target field is the same as a 
field involved in expression 
evaluation, an intermediate area is 
required to develop the result (unless 
otherwise stated in the module 
description summaries). For example, 
A = B || A requires an intermediate 
field, but A = A 6 B does not. 

2. Padding of fixed-length strings does 
not occur automatically when a string 
operation is performed, except in the 
case of assignment of fixed-length 
character strings and fixed-length 
byte-aligned bit strings. Separate 
routines are available for padding. 



r 














-T" 






PL/I 




PL/I 




Bit String 


|( 


Character | 




Operation 




Function 


h 






H 


String j 






"T~ ~ 












General 


| Byte-aligned | 




h 




-+- 




-+- 




4 


-+■ 


.| 




And 




- 




Use BOOL 


j IHEBSA 




- | 




Or 




- 




Use BOOL 


| IHEBSO 




| 




Not 




- 




Use BOOL 


| IHEBSN 




| 




Concatenate | 


REPEAT 




IHEBSK 


| 




IHECSK j 




Compare 




- 




I HE BSD 


| IHEBSC 




IHECSC | 




Assign 




- 




IHEBSK 


| IHEBSM 




IHECSM | 




Fill 




- 




IHEBSM 


| 




IHECSM | 




- 




HIGH/LOW 




- 


| 




IHECSM | 




- 




SUBSTR 




IHEBSS 


j 




IHECSS | 




- 




INDEX 




IHEBSI 


| 




IHECSI | 




- 




BOOL 




IHEBSF 


j 




j 



L J J. A i J 



Figure 47. String Operations and Functions 
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CHAPTER 9: MODULE SUMMARIES 



This section provides information about 
individual modules of the PL/ 1 Library. It 
serves as an introduction to the more 
detailed accounts given in the prefaces to 
the program listings. A brief statement of 
function is given; also provided are full 
specifications of linkage and inter-modular 
dependency. Since many library modules 
invoke the execution error package 
(IHEERR), no reference is made to this 
module in the 'Calls* section. Appendix G 
gives the lengths of the modules and 
indicates their locations (SYSl.PLlLIB or 
SYSl.LINKLIB). 



CONTROL PROGRAM INTERFACES 

The 'Calls* and * Called by* sections 
include the use of the LINK and XCTL macros 
to pass control. 



DATA PROCESSING 



All integral values specified in the 
'Linkage' section of the module description 
will be represented internally as fullword 
binary integers. Target fields will also 
be fullwords unless otherwise specified or 
implied (for example, for long 
floating-point results) . 

When FIXED data is passed to the 
library, a DED is associated with it in the 
linkage. In cases where the DED is not 
interrogated, the appropriate entry in the 
'Linkage* section is marked with an 
asterisk. 

Complex arguments are assumed to have 
real and imaginary parts stored next to 
each other in that order, so that the 
address of the real part suffices for both 
of them. Both parts are described by the 
same DED. 



I/O Editing and Data Conversions 



Strings ; A source string field may 
coincide with a target string field in the 
modules listed in Figure 48. It should be 
noted that use of the same address for the 
dope vectors of source string and target 
string is not generally permitted, even 
though the string fields themselves may be 
overlapped. The exceptions to this are the 
entry points IHEBSKK and IHECSKK, where a 
considerable saving of time can be obtained 
by using the same address for both the 
first source and target SDVs. 



f 


1 


Source/target coincidence 


1 




h 






H 






~T~ "" — — — 


| Module 




First source 


| Either source 




| IHEBSA 


"+- 


field only 


| field 


H 


Yes 


| IHEBSO 




- 


| Yes 




| IHEBSK 




Yes 


j 




| IHEBSM 




Yes 


| 




| IHEBSF 




- 


| Yes 




| IHECSK 




Yes 


| 




| IHECSM 


-X- 


Yes 







Figure 48. Coincidence of Source and 

Target Fields in some string 
Modules 

The first byte of the result produced by 
the comparison modules IHEBSC, IHEBSD, and 
IHECSC contains: 



Bits 



Contents 



to 1 Instruction length code 01 

2 to 3 Condition code as below 

H to 7 Program mask (calling routine) 

The condition code is set as follows : 

00 Strings equal 

01 First string compares low at first 
inequality 

10 First string compares high at first 
inequality 



Arithmetic ; Target fields may, if desired, 
be overlapped with source fields in all 
cases except IHEXIU, IHEXIV, IHEXIW, 
IHEXIZ, IHEXXL and IHEXXS. 



Target fields may, if desired, be 
overlapped with source fields in all cases 
except IHEVSA, IHEVSB, IHEVSC, IHEVSD, 
IHEVSE, and IHEVSF. 



Mathematical : Target fields may, if 
desired-, be overlapped with source fields 
in all cases except IHEEFL, IHEEFS, IHELNW, 
IHELNZ, IHESQW and IHESQZ. 
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MODULE SUMMARIES 



Linkage: 



IHEABN 

Entry point: IHEABND 

Function: 

Default module for system ABEND feature. 
Sets function code in register 15. 

Linkage: 

None 

Called by: IHEERR 

IHEABU 

Entry point: IHEABUO 

Function: 

ABS(z), where z is complex fixed-point 
binary. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 
A(z) 
*A(DED for Z) 
A (Target) 
*A(Tarqet DED) 

Called by: Compiled code 

IHEABV 

Entry point: IHEABVO 

Function: 

ABS(z), where z is complex fixed-point 
decimal. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (DED for z) 

A (Target) 

A (Target DED) 

Called by: Compiled code 

IHEABW 

Calls: IHESQS 

Entry point: IHEABWO 

Function: 

ABS(z), where z is complex short 
floating-point. 



RA: A (Parameter list) 
Parameter list: 

A(z) 

A(Target) 

Called by: Compiled code, IHESQW 



IHEABZ 

Calls: IHESQL 

Entry point: IHEABZO 

Function: 

ABS(z), when z is complex long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code, IHESQZ 

IHEADD 

Calls: IHEAPD 

Entry point: IHEADDO 

Function: 

ADD(x,y, p,q) , where x and y are real 
fixed-point decimal, and (p,q) is the 
target precision* 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (DED for x) 

A(y) 

A(DED for y) 

A(Target) 

A (Target DED) 

Called by: Compiled code, IHEADV 

IHEADV 

Calls: IHEADD 

Entry point: IHEADVO 

Functions 

ADD(w,z,p,q) , where w and z are complex 
fixed-point decimal, and (p,q) is the 
target precision. 
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Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(w) 

A(DED for w) 

A(z) 

A(DED for z) 

A (Target) 

A (Target DED) 

Called by: Compiled code 



IHEAPD 

Calls: IHEERRB 

Entry point IHEAPDA 

Function: 

To assign x to a target with precision 
<Pa# <3a) t where x is real fixed-point 
decimal with precision (p lf qj.)# and p x 
< 31. 

Linkage: 

RA: A(x) 

RB: A (DED for x) 

RC: A (Target) 

RD: A (DED for target) 

Called by: IHEADD, IHEDW, IHEMPV 

Entry point IHEAPDB 

Function: 

To convert x to precision (31, q a ), 
where x is real fixed-point decimal 
with precision (p 1# qi), and p ± <S 31. 

Linkage: As for IHEAPDA 

Called by: IHEADD, IHEDW 
IHEATL 
Entry point IHEATLl 

Function: 

ATAN(x), where x is real long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 



Entry point IHEATL2 

Function: 

ATAN(y,x), where x and y are real long 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(y) 

A(x) 

A (Target) 

Called by: compiled code, IHEATZ, IHELNZ 

Entry point IHEATL3 

Function: 

ATAND(x), where x is real long 
floating-point.. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

Mx) 

A (Target) 

Called by: Compiled code 

Entry point IHEATLl 

Function: 

ATAND(y,x), where x and y are real long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

My) 

Mx) 

M Target) 

Called by: Compiled code 
IHEATS 
Entry point IHEATSl 

Function: 

AT AN (x), where x is real short 
floating-point. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 
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Entry point IHEATS2 
Function: 

ATAN(y,x), where x and y are real short 
floating-point- 
Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(y) 

A(x) 

A (Target) 

Called by: Compiled code, IHEATW, IHELNW 

Entry point I HEATS 3 
Function: 

ATAND(x), where x is real short 
floating-point- 
Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 

Entry point IHEATSU 

Function : 

ATAND(y,x), where x and y are real 
short floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(y) 

A(x) 

A (Target) 

Called by: Compiled code 



IHEATW 

Calls: IHEATS, IHEHTS 

Entry point IHEATWN 

Function: 

ATAN(z), where z is complex short 
floating-point. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code 



Entry point IHEATW H 

Calls: IHEATS2, IHEHTS 

Function: 

ATANH(z), where z is complex short 
floating-point. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

Mz) 

A (Target) 

Called by: Compiled code 
IHEATZ 

Calls: IHEATL, IHEHTL 
Entry point IHEAT2N 
Calls: IHEATL2, IHEHTL 

Function: 

ATAN(z), where z is complex long 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (z) 

h (Target) 

Called by: Compiled code 

Entry poin t IHEATZH 

Calls: IHEATL2, IHEHETL 

Function: 

ATANH (z), when z is complex long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (z) 

A (Target) 

Called by: Compiled code 
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IHEBEG 



Function: 



Calls: 

Supervisor (LINK, GETMAIN, FREEMAIN) , 
IHETOM 

Entry point IHEBEGA 

Function: 

Links to IHETOM to issue a WTO macro 
instruction if the PRV is longer than 
4096 bytes. 

Linkage: None 

Called by: IHESAP, IHETSA 

Entry point IHEBEGN 

Function: 

Links to IHETOM to issue a WTO macro 
instruction if the program does not 
have a main procedure. 

Linkage: None 

Called by: IHESAP, IHETSA, IHEMAIN 

IHEBSA 

Entry point: IHEBSAO 

Function: 

AND operator (6) for two byte-aligned bit 
strings. 

Linkage: 

RA: A(SDV of first operand) 
RB: A(SDV of second operand) 
RC: A(SDV of target field) 

Called by: Compiled code 

IHEBSC 

Entry point: IHEBSCO 

Function: 

To compare two byte- aligned bit strings. 

Linkage: 

RA: A(SDV of first operand) 
RB: A(SDV of second operand) 
RC: A (Target) 

Called by: Compiled code 

IHEBSD 

Entry points IHEBSDO 



To compare two bit strings with any 
alignment. 



Linkage: 

RA: MSDV of first operand) 
RB: A(SDV of second operand) 
RC: A (Target) 

Called by: Compiled code 

IHEBS F 

Entry point: IHEBSFO 

Function: 

BOOL (Bit string, bit string, string n t 
na n3 n<*) . 

Linkage: 

RA: A (Parameter list) 

Parameter list: 

A(SDV of first source string) 

A(SDV of second source string) 

A (Full word containing bit pattern n^. n 2 

n 3 n„ right justified) 
A(SDV of target field) 

Called by: Compiled code 

IHEBSI 

Entry point: IHEBSIO 

Function: 

INDEX (Bit string, bit string). 

Linkage: 

RA: A (Parameter list) 

Parameter list: 

A(SDV of first source string) 
A(SDV of second source string) 
A (Target field) 

Called by: Compiled code 

IHEBSK 

Entry point IHEBSKA 

Function: 

To assign a bit string to a target 
field. 

Linkage: 

RA: A(SDV of source string) 
RB: A(SDV of target field) 

Called by: Compiled code 



Chapter 9: Module summaries 91 



Entry point IHEBSKK 



IHEBSN 



Function: 



Concatenate operator ( | | ) for bit 
strings. 



Linkage: 

RA: ACSDV of first operand) 
RB: A(SDV of second operand) 
RC: ACSDV of target field) 

Called by: Compiled code, IHESTGA 

Entry point IHEBSKR 

Function: REPEAT (Bit string ,n). 

Linkage : 

RA: A(SDV of source string) 

RB: A(n) 

RC: ACSDV of target field) 

Called by: Compiled code 
IHEBSM 
Entry point IHEBSMF 

Function: 

To assign a byte-aligned bit string to 
a byte-aligned fixed-length target. 

Linkage: 

RA: A(SDV of source string) 
RB: ACSDV of target field) 

Called by: Compiled code 

Entry point IHEBSMV 

Function: 

To assign a byte-aligned bit string to 
a byte-aligned VARYING target. 

Linkage: As for IHEBSMF 

Called by: Compiled code 

Entry point IHEBSMZ 

Function: 

To fill out a bit string from its 
current length to its maximum length 
with zero bits. 

Linkage: RA: ACSDV) 

Called by: Compiled code 



Entry point: IHEBSNO 

Function: 

NOT operator ^ ) for a byte-aligned bit 
string. 

Linkage: 

RA: ACSDV of operand) 

RB: ACSDV of target field) 

Called by: Compiled code 

IHEBSO 

Entry point: IHEBSOO 

Function: 

OR operator C|) for two byte-aligned bit 
strings. 

Linkage: 

RA: ACSDV of first operand) 
RB: ACSDV of second operand) 
RC: ACSDV of target field) 

Called by: Compiled code 

IHEBSS 

Entry point IHEESS2 

Function : 

To produce an SDV describing the 
pseudo-variable or function SUBSTR CBit 
string, i) . 

Linkage: 

RA: AC Parameter list) 
Parameter list: 

ACSDV of source string) 

ACi) 

Dummy argument 

ACField for target SDV) 

Called by: Compiled code 

Entry point IHEBSS 3 

Function: 

To produce an SDV describing the 
pseudo-variable or function SUBSTR CBit 
string, i, j). 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

ACSDV of source string) 

ACi) 
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A(j) 

A (Field for target SDV) 



Called by: Compiled code 
IHEBST 

Calls: IHEBSF, IHEBSI, IHEBSS 

Entry point: IHEBSTA 

Function: Translate bit string 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (SOURCE/TARGET SDV) 

A (REPLACEMENT SDV) 

A( POSITIONAL SDV) 

Called by: Compiled code. 
IHEBSV 

Calls: 

Entry point: IHEBSVA 

Function: Verify bit string 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (El SDV) 

A(E2 SDV) 

A (Result field) 

Called by: Compiled code. 

IHECFA 

Entry point: IHECFAA 

Function: 

ONLOC: Locates the BCD name of the 
procedure that contains the PL/I 
interrupt that caused entry into the 
current on-unit. If ONLOC is specified 
outside an on-unit, a null string is 
returned. 

Linkage: 

RA: A (Parameter list) 
Parameter list: A (Target SDV) 

Called by: compiled code 

IHECFB 

Entry point: IHECFB A 

Function: 

ONCODE: Returns a value corresponding to 
the condition which caused the interrupt. 



If specified outside an on-unit, a unique 
code (0) is returned. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 

A(4-byte word-aligned target) 

Called by: Compiled code 

IHECFC 

Entry point: IHECFCA 

Function: 

ONCOUNT: Returns a value equal to the 
number of PL/I conditions and program 
exceptions, including the current one, 
that have yet to be processed. A zero 
value is returned if: 

1. ONCOUNT is used outside an ON unit, 
or 

2. ONCODNT is used in an ON unit entered 
because of a precise interrupt or a 
single imprecise interrupt 

(This built-in function is used in 
connection with the Model 91 and 195 
option) 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(*»-byte word-aligned target) 

Called by: Compiled code 

IHECKP 

Calls: Supervisor 

Entry point: IHECKPS 

Function: 

Requests the control program checkpoint 
facility to save main storage areas and 
control information so that the job 
step may be restarted from the check- 
point. 

Linkage: 

IHECKPS: 

RA: A (Parameter list) 
Parameter list: 

Mddnarae SDV) 

A(checkid SDV) 

A (data set organization SDV) 

A (Return code field) 

Called by: 

Compiled code (CALL IHECKPS statement) 
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Entry points IHECKPT 

Function: As for IHECKPS 

Linkage: none 

Called by: compiled code (CALL IHECKPT 
statement) 

IHECLT 
Calls: 



IHESA, Supervisor (CLOSE, DCBD, DELETE, 
FREEMAIN, FREEPOOL, RETURN) 



Entry point IHECLT A 
Function: 

Close files: 

1. Free FCB. 

2. Set file register to zero. 

3. Remove file from IHEQFOP chain. 

4. Delete interface modules loaded for 
record-oriented I/O. 

5. Purge outstanding I/O events, 
setting event variables complete, 
abnormal, and inactive. 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

A (CLOSE parameter list) 

A (Private adcons) 

CLOSE parameter list: 
A(DCLCB X ) 
(Reserved) 
(Reserved) 



A(DCLCBn) 

(Reserved) 

(Reserved) 

(High-order byte of last argument 

indicates end of parameter list) 

Called by: IHEOCL 

Entry point IHECLTB 

Function: 

To close all files when a task is 
terminated. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

F( number of files to be closed*'*) 

A(Adcon list) 

A (1st FCB) 



A(nth FCB) 

(High-order byte of last argument 

indicates end of parameter list.) 



Called by: IHEOCL 
IHECNT 
Entry point IHECNTA 

Function: 

Returns count of scalar items 
transmitted on last I/O operation. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(DCLCB) 

A (Full word) 

Called by: Compiled code 
Entry point IHECNTB 

Function: 

Returns current line number (LINENO). 

Linkage: As for IHECNTA 
Called by: Compiled code 
IHECSC 

Entry point: IHECSCO 
Function: 

To compare two character strings. 

Linkage : 

RA: A(SDV of first operand) 
RB: A(SDV of second operand) 
RC: A (Target) 

Called by: Compiled code 

IHECSI 

Entry point: IHECSIO 

Function: 

INDEX (Character string, character 
string). 
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Linkage: 

RA: A(Pararaeter list) 

Parameter list: 

A(SDV of first source string) 
A (SDV of second source string) 
A (Target field) 

Called by: Compiled code 



IHECSK 

Entry point IHECSKK 

Function: 

Concatenate operator ( | | ) for character 
strings. 

Linkage : 

RA: A(SDV of first operand) 
RB: A(SDV of second operand) 
RC: ACSDV of target field) 

Called by: Compiled code 

Entry point IHECSKR 

Function: 

REPEAT (Character string, n) . 

Linkage : 

RA: A(SDV of source string) 

RB: A(n) 

RC: A (SDV of target field) 

Called by: Compiled code 
IHECSM 
Entry point IHECSMF 

Function: 

To assign a character string to a 
fixed- length target. 

Linkage : 

RAs A(SDV of source string) 
RB: A(SDV of target field) 

Called by: Compiled code 

Entry point IHECSMV 

Function: 

To assign a character string to a 
VARYING target. 
Linkage: As for IHECSMF 

Called by: Compiled code 



Entry point IHECSMB 

Function: 

To fill out a character string from its 
current length to its maximum length 
with blanks. 

Linkage: 

RA: A(SDV) 

Called by: Compiled code 
Entry point IHECSMH 

Function: HIGH 

Linkage: As for IHECSMB 

Called by: Compiled code 
Entry point IHECSML 

Function: LOW. 

Linkage: As for IHECSMB 

Called by: Compiled code 

IHECSS 

Entry point IHECSS2 

Function: 

To produce an SDV describing the 
pseudo-variable or function SUBSTR 
(Character string, i) . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(SDV of source string) 

A(i) 

Dummy argument 

h (Field for target SDV) 

Called by: Compiled code 

Entry point IHECSS3 

Function: 

To produce an SDV describing the 
pseudo- variable or function SUBSTR 
(Character string, i, j). 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (SDV of source string) 

Mi) 

A(j) 

A (Field for target SDV) 
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Called by: Compiled code 

IHECST 

Calls: 
Entry point: IHECSTA 
Function: 

Supplements translate character string 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (SDV Of SOURCE/TARGET) 
A(SDV of REPLACEMENT) 
A(SDV Of POSITIONAL) 
A (Translate table) 

Called by: Compiled code. 
IHECSV 

Calls: 

Entry point: IHECSVA 

Function: Supplements verify character 
string 

Linkage: RA:A( Parameter list) 
Parameter list: 
A(E1 SDV) 
A(E2 SDV) 

A (Translate table) 
A(Result field) 

Called by: Compiled code. 

IHECTT 

Calls: 

IHETSA, Supervisor (CLOSE, DCBD, DELETE, 
DEQ, FREEMAIN, FREEPOOL, RETURN) 

Entry point IHECTTA 

Function: 

Close files in a multitasking 
environment: 

1. Free FCB. 

2. Set file register to zero. 

3. Remove file from IHEQFOP chain. 

4. Delete interface modules loaded for 
record-oriented I/O. 

5. Purge outstanding I/O events, 
setting event variables complete, 
normal, and inactive. 



(i) Check that the file is in 
the IHEQFOP chain for the 
current task. 



(ii) Free IOCBs, setting 

associated EVENT variables 
complete, abnormal, and 
inactive. 

(iii) Set EVENT variables in TEVT 
chain complete, abnormal, 
and inactive. 

(iv) For REGIONAL EXCLUSIVE 

files, or INDEXED EXCLUSIVE 
files with unblocked 
records, dequeue locked 
records and free EXCLUSIVE 
blocks in the TXLV chain. 

(v) For INDEXED EXCLUSIVE files 
with blocked records, unlock 
the files. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A (CLOSE parameter list) 

A (Private adcons) 

CLOSE parameter list: 
A(DCLCB,) 
A(IDENT SDV 1 )/0 
A(IDENT DED, )/0 



A(DCLCB n ) 

A(IDENT SDV n )/0 

A(IDENT DED n )/0 

(High-order byte of last argument 

indicates end of parameter list) 

Called by: IHEOCT 

Entry point IHECTTB 

Function: 

To close all files when a task is 
terminated. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

F (number of files to be closed***) 

A(Adcon list) 

Adst FCB) 



A (nth FCB) 

(High-order byte of last argument 

indicates end of parameter list) 

Called by: IHEOCT 
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Entry point IHECTTC 

Function: 

Implicit close for tasks detached at 
undetermined points. 

Linkage: as for IHECTTB 

Called by: IHEOCT 

IHEDBN 

Calls: IHEDMA, IHEUPA, IHEUPB 

Entry point: IHEDBNA 

Function: 

To convert a bit string to an arithmetic 
target with a specified base, scale, 
mode, and precision. 

Linkage: 

RA: A (Source SDV) 
RB: A (Source DED) 
RC: A(Target) 
RD: A (Target DED) 

Called by: 

Compiled code, IHEDOA, IHEDOE, IHEDOM 
IHEDCN 

Calls: IHEDMA, IHEUPA, IHEUPB, IHEVQB 
Entry point IHEDCNA 

Function: 

To convert a character string 
containing a valid arithmetic constant 
or complex expression to an arithmetic 
target with specified base, scale, 
mode, and precision. The ONSOURCE 
address is stored. 

Linkage: 

RA: A (Source SDV) 
RB: A (Source DED) 
RC: A (Target) 
RD: A (Target DED) 
WOFD: A (Source SDV) 

Called by: 

Compiled code, IHEDIB, IHEDOA, IHEDOE 

Entry point IHEDCNB 

Function: 

As for IHEDCNA, but the ONSOURCE 
address is not stored. 



Linkage: 

As for IHEDCNA, but without WOFD 
Called by: As for IHEDCNA 

IHEDDI 
Calls: 

IHEDDJ, IHEIOF, IHELDI, IHESAP, IHETSA 
Entry point IHEDDI A 

Function: 

To read data from an input stream and 
assign it to internal variables 
according to symbol table information 
conventions. Restrictive data list. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 
A (Symbol table*) 



A (Symbol table n ) 

(High-order byte of last argument 
indicates end of parameter list.) 

Called by: Compiled code 

Entry point IHEDDI B 

Function: 

As for IHEDDIA, but no data list. 

Linkage: 

RA: A( Parameter list) 

Parameter list: A (Symbol table chain) 

Called by: Compiled code 

IHEDDJ 

Entry point: IHEDDJ A 

Function: 

To compute the address of an array 
element from source subscripts and an 
ADV. 

Linkage: 

RA: A(ADV) 

RB: A (DED) 

RC: A (Field for element address) 

RD: A (Symbol table entry, 2nd part) 

RE: A (SDV for subscripts) 

Called by: IHEDDIA 
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IHEDDO 
Calls: 

IHEDDP, IHEIOF, IHELDO, IHEPRT 

Entry point IHEDDO A 

Function: 

To convert data according to 
data- directed output conventions and to 
write it onto an output stream. For 
scalar variables and whole arrays. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Symbol table entry ± ) 



A (Symbol table entry n ) 
(High-order byte of last argument 
indicates end of parameter list.) 

Called by: Compiled code 

Entry point IHEDDOB 

Function: 

As for IHEDDOA but for array variable 
elements. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Symbol table entry 4 ) 

A (Element address*.) 



A (Symbol table entry n ) 
A (Element address n ) 
(High-order byte of last argument 
indicates end of parameter list. ) 

Called by: Compiled code 



Entry point I HEP DOC 

Function: 

To terminate data-directed transmiss- 
ion. 

Linkage : None 

Called by: Compiled code 



Entry point IHEDDO D 

Function: 

As for IHEDDOA, but used to support the 
CHECK condition* 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Symbol table entry) 

A (Element address) 

Called by: IHEERR, IHESAPA 

Entry point IHEDDOE 

Function: 

In the absence of a data list, to 
convert all data known within a block 
according to data- directed output 
conventions and to write it onto an 
output stream. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (First symbol table entry) 

Called by: Compiled code 
IHEDDP 
Entry point IHEDDPA 

Function: 

To prepare an array for subscript 
output operation, and to address the 
first element. 

Linkage: 

RA: A( Field for A(VDA)) 

RB: A(FCB) 

RC: A( Symbol table entry, 2nd part) 

Called by: IHEDDO, IHEDDT 

Entry point IHEDDPB 

Function: To perforin subscript output. 

Linkage: 

RA: A (Parameter list) 
Parameter list: A(VDA) 

Called by: IHEDDO, IHEDDT 

Entry point IHEDDPC 

Function: 

To address the next element. 
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Linkage: 



Linkage: 



RA: A (Parameter list) 
Parameter list: A(VDA) 
Return codes : 

BR=0: Another element 
BR=4: End of array 

Called by: IHEDDO, IHEDDT 



Entry point IHEDDPD 

Function: 

To prepare an array for subscript 
output operation for a given element. 



Linkage: 

RA: A(Field for A(VDA)) 

RB: A(FCB) 

RC: A (Symbol table entry, 2nd part) 

RD: A (Element) 

Called by: IHEDDO, IHEDDT 



IHEDDT 

Calls: 

Supervisor (DEQ,ENQ), IHEDDP, IHEIOF, 
IHELDO, IHEPTT 



Entry point IHEDDTA 

Function: 

To convert data according to 
data-directed output conventions and to 
write it onto an output stream. For 
scalar variables and whole arrays in a 
multitasking environment. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Symbol table entry,) 



A (Symbol table entry n ) 
(High-order byte of last argument 
indicates end of parameter list) 



Called by: Compiled code 



Entry point IHEDDTB 

Function: 

As for IHEDDTA but for array variable 
elements. 



RA: A( Parameter list) 

Parameter list: 

A (Symbol table entry,) 
A (Element address,) 



A( Symbol table entry n ) 
A (Element address n ) 
(High-order byte of last argument 
indicates end of parameter list) 

Called by: Compiled code 

Entry point IHEDDTC 

Function: 

To terminate data- directed transmission 
in a multitasking environment. 

Linkage: None 

Called by: Compiled code 

Entry point IHEDDTD 

Function : 

As for IHEDDTA, but used to support the 
CHECK condition in a multitasking 
environment. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A (Symbol table entry) 

A (Element address) 

Called by: IHEERR, IHETSA 

Entry point IHEDPTE 

Function: 

In the absence of a data list, to convert 
all data known within a block according 
to data- directed output conventions and 
to write it onto an output stream in a 
multitasking environment. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 

A (First symbol table entry) 

Called by: Compiled code, IHEDDTA 

IHEDIA 

Calls: 

IHEDMA, IHEDNB, IHEDNC, IHEIOD, IHEUPA, 
IHEUPB, IHEVCA, IHEVQB, IHEVSA, IHEVSC 



Chapter 9: Module Summaries 99 



Entry point IHEDIAA 

Function: 

To direct the conversion of F format 
data to an internal data type. 



Entry point: IHEDIDA 

Function: 

To direct the conversion of external B 
format data to an internal data type. 



Linkage: 

RA: A (Target or target dope vector) 
RB: A (Target DED) 
RC: A (FED) 

Called by: Compiled code, IHEDIM 

Entry point IHEDIAB 

Function : 

To direct the conversion of E format 
data to an internal data type. 

Linkage: As for IHEDIAA 

Called by: As for IHEDIAA 

IHEDIB 

Calls: 

IHEDCN, IHEIOD, IHEKCD, IHEVSC, IHEVSD, 
IHEVSE 

Entry point IHEDIBA 

Function: 

To direct the conversion of A format 
data to an internal data type. 

Linkage: 

RA: A (Target or target dope vector) 
RB: A (Target DED) 
RC: A (FED) 

Called by: Compiled code 

Entry point IHEDIBB 

Function: 

To direct the conversion of pictured 
character string data to an internal 
data type. 

Linkage: As for IHEDIBA 

Called by: Compiled code 

IHEDID 

Calls: 

IHEDBN, IHEDMA, IHEIOD, IHEUPA, IHEUPB, 
IHEVSC, IHEVSD, IHEVSE 



Linkage : 

RA: A (Target or target dope vector) 
RB: A (Target DED) 
RC: A (FED) 

Called by: Compiled code 



IHEDIE 

Calls: 

IHEDMA, IHEDMB, IHEDMC, IHEIOD, IHEKCA, 
IHEKCB, IHEUPA, IHEUPB, IHEVSC, IHEVSD, 
IHEVSE 



Entry point: IHEDIEA 



Function: 

To direct the conversion of external data 
with a numeric picture format to an 
internal data type. 



Linkage : 

RA: A (Target or target dope vector) 
RB: A (Target DED) 
RC: A (FED) 

Called by: Compiled code, IHEDIM 



IHEDIL 

Entry point IHEDILA 

Function: 

To set up appropriate error handling 
when no width specification for A 
format input is given. 

Linkage: None 

Called by: Compiled code 

Entry point IHEDILB 

Function: 

As for IHEDILA, but B format 

Linkage: None 

Called by: Compiled code 
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IHEDIM 



Linkage : 



Calls: 

IHEDIA, IHEDIE, IHEIOD, IHEKCA, IHEVCA, 
IHEVCS 

Entry point: IHEDIMA 

Function : 

To direct the conversion of external data 
with C format to an internal data type. 

Linkage: 

RA: A (Target or target dope vector) 

RB: A (Target DED) 

RC: A (Real format director) 

RD: A(Real FED) 

RE: A (Imaginary format director) 

RF: A (Imaginary FED) 

Called by: Compiled code 

IHEDMA 

Transfers control to: 

IHEVFD, IHEVFE, IHEVKB, IHEVKC, IHEVPE, 
IHEVPF, IHEVPG, IHEVPH 



Entry point: 
Function: 



IHEDMAA 



To set up the intermodular flow to effect 
conversion from one arithmetic data type 
to another. 

Linkage: 

RA: A (Source) 
RB: A (Source DED) 
RC: A (Target) 
RD: A (Target DED) 

Called by: 

Compiled code, I/O directors, IHEDBN, 
IHEDCN, IHEDNB, IHEDNC, IHELDI, IHEPDF, 
IHEPDX, IHEPSF, IHEPSX, IHESMF, IHESMX, 
IHESSF, IHESSX, IHEUPB, IHEVCS, IHEVFA, 
IHEVFB, IHEVFC, IHEVPA, IHEVPB, IHEVPC, 
IHEVPD, IHEVKF, IHEVKG, IHEYGF, IHEYGX 

IHEDNB 

Calls: IHEDMA, IHEVSA 

Entry point: IHEDNB A 

Function : 

To convert an arithmetic source with 
specified base, scale, mode, and 
precision to a fixed-length bit string or 
a VARYING bit string of specified length. 



RA: A (Source) 
RB: A (Source DED) 
RC: A (Target SDV) 
RD: A (Target DED) 

Called by: 

Compiled code, IHEDI, IHEDIE, IHEDOD, 
IHEVCS 

IHEDNC 

Calls: 

IHEDMA, IHEUPA, IHEVQC, IHEVSC, IHEVSE 

Entry point: IHEDNC A 

Function: 

To convert an arithmetic source of 
specified base, scale, mode, and 
precision to a character string or a 
pictured character string. 



Linkage : 

RA: A (Source) 
RB: A (Source DED) 
RC: A (Target SDV) 
RD: A (Target DED) 

Called by: 

Compiled code, IHEDIA, IHEDIE, IHEDOA, 
IHEDOB, IHELDI, IHELDO, IHEVCS 

IHEDOA 

Calls: 

IHEDBN, IHEDCN, IHEDMA, IHEIOD, IHEVQC 



Entry point IHEDOAA 

Function: 

To direct the conversion of internal 
data to external F format. 

Linkage: 

RA: A (Source or source dope vector) 
RB: A( Source DED) 
RC: A (FED) 

Called by: Compiled code 

Entry point IHEDOAB 

Function: 

To direct the conversion of internal 
data to external E format. 
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Linkage: As for IHEDOAA 



Linkage: 



Called by: As for IHEDOAA 

IHEDOB 

Calls: 

IHEDNC, IHEIOD, IHEVSB, IHEVSC, IHEVSE, 
IHEVSF 

Entry point IHEDOB A 

Function: 

To direct the conversion of internal 
data to external A(w) format. 

Linkage : 

RA: A (Source or source dope vector) 
RB: A (Source DED) 
RC: A (FED) 

Called by: Compiled code 

Entry point IHEDOBB 

Function: 

To direct the conversion of internal 
data to external A format. 

Linkage: 

RA: A (Source or source dope vector) 
RB: A (Source DED) 

Called by: Compiled code 

Entry point IHEDOBC 

Function : 

To direct the conversion of internal 
data to external pictured character 
format. 

Linkage: As for IHEDOBA 

Called by: Compiled code 
IHEDOD 

Calls: IHEDNB, IHEIOD, IHEVSB, IHEVSC 
Entry point IHEDODA 

Function: 

To direct the conversion of internal 
data to external B(w) format. 



RA: A( Source or source dope vector) 
RB: A (Source DED) 
RC: A (FED) 

Called by: Compiled code 



Entry point IHEDODB 

Function : 

To direct the conversion of internal 
data to external B format. 

Linkage: 

RA: A (Source or source dope vector) 
RB: A (Source DED) 

Called by: Compiled code 
IHEDOE 
Calls: 

IHEDBN, IHEDCN, IHEDMA, IHEIOD, IHEVSB 

Entry point: IHEDOEA 

Function: 

To direct the conversion of internal data 
to external data with a numeric picture 
format. 

Linkage: 

RA: A (Source or source dope vector) 
RB: A (Source DED) 
RC: A (FED) 

Called by: Compiled code, IHEDOM 

IHEDOM 

Calls: 

IHEDBN, IHEUPA, IHEUPB, IHEVCA, IHEVCS 

Entry point: IHEDOMA 

Function: 

To direct the conversion of an internal 
data type to external C format data. 

Linkage : 

RA: A (Source or source dope vector) 

RB: A (Source DED) 

RC: A (Real format director) 

RD: A (Real FED) 

RE: A( Imaginary format director) 

RF: A (Imaginary FED) 

Called by: Compiled code 
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IHEDSP 

Calls: Supervisor (WAIT, WTO, WTOR, 

GETMAIN, POST, FREEMAIN, CHAP) 

Entry point: IHEDSPA 



Entry point IHEDUMP 

Function : 

Dump all tasks and terminate major 
task. 



Function: 

To write a message on the operator's 
console, with or without a reply. The 
EVENT option can be used for a message 
with a reply. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(SDV for message) 
A(SDV for reply) 
A (Event variable) 
(The parameter list is either one, 
two, or three elements long, 
depending on the use of the REPLY and 
EVENT options. The high-order byte 
of the last argument indicates the 
end of the parameter list.) 

Called by: Compiled code 



IHEDUM 
Calls: 



Supervisor (ABEND, LINK, POST, SNAP, 
WAIT), IHEQMA, IHESAFQ IHETSA, IHEZZC 

Entry point IHEDUMC 

Function: 

Dump current task and then continue 
execution. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

F (Number in range through 255) 

Called by: Compiled code (CALL IHEDUMC 
statement) 

Entry point IHEDUMJ 

Function : 

Dump all tasks and then continue 
execution. 

Linkage: As IHEDUMC 

Called by: Compiled code (CALL IHEDUMJ 
statement) 



Linkage: As IHEDUMC 



Called by: Compiled code (CALL IHEDUMP 
statement) 



Entry point IHEDUMT 



Function: 



Dump current task and then terminate 
it. 



Linkage: As IHEDUMC 



Called by: Compiled code (CALL IHEDUMT 
statement) 



IHEDVU 



Entry point: IHEDVUO 



Function: 



DIVlDE(w,z,p,q) , where w and z are 
complex fixed-point binary, and (p,q) is 
the target precision. 



Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(w) 

A(DED for w) 

A(z) 

A(DED for z) 

A (Target) 

A(DED for target) 

Called by : Compiled code 

IHEDW 

Calls: IHEAPD 

Entry point: IHEDWO 

Function : 

DIVIDE (w, z,p, q) , where w and z are 
complex fixed-point decimal, and (p,q) is 
the target precision. 
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Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(w) 

A(DED for w) 

A(Z) 

A(DED for z) 

A (Target) 

A(DED for target) 

Called by: Compiled code 



IHEDZW 



Entry point: IHEDZWO 



Function: 

z A /z a , where z ± and z a are complex short 
floating-point . 



Linkage: 

RA: A(z ± ) 
R6: A(z 2 ) 
RC: A (Target) 

Called by: Compiled code 

IHEDZZ 

Entry point: IHEDZZO 

Function : 

z±/z a , where z ± and z 2 are complex long 
floating-point. 

Linkage : 

RA: A(z ± ) 
RB: A(z a ) 
RC: A (Target) 

Called by: Compiled code 

IHEEFL 

Calls: IHEEXL 

Entry point IHEEFLF 

Function: 

ERF(x), where x is real long 
floating-point. 
Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 



Entry point IHEEFLC 

Function: 

ERFC(x), where x is real long 
floating-point. 

Linkage: As for IHEEFLF 

Called by: Compiled code 
IHEEFS 

Calls: IHEEXS 
Entry point IHEEFSF 

Function: 

ERF(x), where x is real short 
floating-point. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 

Entry point IHEEFSC 

Function: 

ERFC(x), where x is real short 
floating-point . 

Linkage: As for IHEEFSF 

Called by: Compiled code 

IHEERD 

Function: 

Non-resident part of the error- handling 
routines. It contains the 
data- processing error messages, and when 
required is dynamically loaded from 
IHEESM (Versions 3 and 4) . 

IHEERE 

Function: 

Non-resident part of the error- handling 
routines. It contains the input/output 
error messages, and when required is 
dynamically loaded from IHEESM (Versions 
3 and 4) . 

IHEERI 

Function: 

Non-resident part of the error- handling 
routines. It contains the remaining 
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error messages, that is, those not 
contained in IHEERD, IKEERE, IHEERO and 
IHEERP, and when required is dynamically 
loaded from IHEESM (Versions 3 and ft) . 

IHEERN 

Function: 

Non-resident part of the error package. 
It contains the error messages, and is 
dynamically loaded as required by IHEERR 
(Version 1) or IHEESS (Version 2). 

IHEERO 

Function: 

Non-resident part of the error-handling 
routines. It contains the error 
messages, and when required is 
dynamically loaded from IHEESM (Versions 
3 and ft). 

IHEERP 

Function: 

Non-resident part of the err or- handling 
routines. It contains the error 
messages, and when required is 
dynamically loaded from IHEESM (Versions 
3 and ft). 

IHEERR 

Calls: 

Supervisor (LINK, SPIE), IHEDDO, IHEDDT, 
IHEERS (Version 1) , IHEESM, IHEESS 
(Version 2), IHEM91, IHEPRT, IHEPTT. 
IHESAP, IHETER, IHETSA 

IHEERRE calls: LINK, ABEND with DUMP and 
STEP options 

Entry point IHEERRA (Program Interrupt ): 

Function: 

To determine the identity of the error or 
condition that has been raised, and to 
determine what action must be taken on 
account of it. Several courses of action 
are possible, including combinations of: 

(1) Entry into an on-unit 

(2) SNAP 

(3) No action - return to program 

(ft) Print error message and terminate 

(5) Print error message and continue 

(6) Set standard results into float 
registers 

(7) Branches to IHEM91 for imprecise 
inter rrupts. 

Linkage: None 

Called by: supervisor 



Entry point IHEERRB (ON Conditions): 

Function: As for IHEERRA. 

Linkage: 

RA: A(DCLCB) (for I/O conditions) 
IHEQERR: Error code 

Called by: Compiled code, library modules 

Entry point IHEERRC (Non-ON errors) : 

Function: As for IHEERRA. 

Linkage: 

RA: A (Two-byte error code) 

A( Four- byte code if source program 
error) 

Called by: Compiled code, library modules 

Entry point IHEERRD (CHECK. CONDITION) : 

Function: As for IHEERRA. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

One* byte error code 

Three- byte A(X) 

X: Symbol table 

X: Symbol table (CHECK variable) , or 
Symbol length and name (CHECK label), 
or 
Identifying CSECT (CONDITION) 

Called by: Compiled code 

Entry point IHEERRE 

Function : 

To accept control when a program 
interrupt occurs in IHEERR or in 
modules that IHEERR calls or links to; 
to link to IHETOM to write a disaster 
message on the console; to terminate 
the program and to provide an operating 
system ABDUMP. 

Linkage: None 

Called by: Supervisor 

IHEERS 

Entry point: IHEERSA 

Function: 

SNAP: To determine and record the 
location of the point of interrupt and to 
print the procedure trace-back 
information associated with it. 
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Linkage : 



Linkage: 



RA: A( Third word of a library VDA to 
be used as a save area and message 
buffer): words 21 to 23 of the VDA 
are used to pass the following 
parameters: 

21: A (Interrupt VDA)/0 
22: A (PRINT routine) 
23: A (Current DSA) 



Called by: IHEERR (Version 1) 



IHEERT 



Function: 



Non-resident part of the error-handling 
routines. It contains the multitasking 
error messages, and is dynamically loaded 
when required from IHEESM or IHETEX 
(Version 4) . 

IHESSM 

Calls: 

Supervisor (DELETE, DEQ, ENQ, LOAD), 
IHEERD, IHEERE, IHEERI, IHEERO, IHEERP, 
IHEERT, IHEPRT, IHEPTT, IHESAP, IHETSA 

Entry point IHEESMA 



Function: 

To print out SNAP and system action 
messages. 

Linkage: 

RA: A (First word of a library VDA to be 
used as a save area and message 
buffer) 

RH: A (Current DSA) 

Also passed are: 

A(IHEPTTB) or A(IHEPRTB) : current LWE 

+ 124 
A(IHETSAL) or A(IHESADE) : current LWE 

♦ 128 
A(IHETSAF) or A(IHESAFD) : current LWE 

+ 132 
Length of PRV: current LWE+102 

Called by: IHEERR (Versions 3 and 4) 

Entry point IHEESMB 

Function: 

To print CHECK (label) system action 
messages. 



RA: A( Label) 

RB: A (Length of label) 

Also passed: 

A(IHEPTTB) or A(IHEPRTB) : Current LWE 
+ 124 

Called by: IHEERR (Versions 3 and 4) 



IHEESS 

Calls: IHEERN, IHEPRT, IHESAP, IHETSA 

Entry point IHEESSA 

Function: 



To print out SNAP and system action 
messages . 



Linkage: 

RA: A( First word of a library VDA to be 
used as a save area and message 
buffer) 

Also passed are: 

A (Interrupt VDA/O): current LWE ♦ 96 

A(Current DSA): current LWE + 100 

A(IHESADE): current LWE ♦ 104 

A(IHESAFE): current LWE + 108 

A (IHEPRT): current LWE ♦ 112 

Called by: IHEERR (Version 2) 

Entry point IHEESSB 

Function: 

To print CHECK (label) system action 
messages . 

Linkage: 

RA: A (Label) 

A (Length of label) 

Also passed: 

A(IHEPRTB): current LWE ♦ 112 

Called by: IHEERR (Version 2) 

IHEEXL 

Entry point: IHEEXLO 

Function : 

EXP(x), where x is real long 
floating-point. 
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Linkage: 



Linkage : 



RA: A ( Parameter list) 
Parameter list: 

A(x) 

A (Target) 



Called by: 



Compiled code, IHEEFL, IHEEXZ, IHESHL, 
IHESNZ, IHETHL, IHEXXL 



IHEEXS 



Entry point: IHEEXSO 



Function: 



EXP(x), where x is real short 
floating-point . 



Linkage: 



RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 



Called by: 



Compiled code, IHEEFS, IHEEXW, IHESHS, 
IHESNW, IHETHS, IHEXXS 

IHEEXW 

Calls: IHEEXS, IHESNS 

Entry point: IHEEXWO 

Function: 

EXP ( z) , where z is complex short 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code, IHEXXW 

IHEEXZ 

Calls: IHEEXL, IHESNL 

Entry point: IHEEXZO 

Function: 

EXP(z), where z is complex long 
floating-point . 



RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code, IHEXXZ 



IHEHTL 



Calls: IHELNL 



Entry point: IHEHTLO 



Function: 



ATANH(x), where x is real long 
floating-point . 



Linkage : 

RA: A(Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code, IHEATZ 



IHEHTS 



Calls: IHELNS 



Entry point: IHEHTSO 



Function : 

ATANH(x), where x is real short 
f loat ing- point . 



Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A(Target) 

Called by: Compiled code, IHEATW 



IHEIBT 

This module is used in a multitasking 
environment and is equivalent to module 
IHEIOB in a non-multitasking environment. 

Calls: 

supervisor (DEQ.ENQ), IHEIOP, IHEOCT 
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Entry point IHEIBTA 

Function: 

To initialize the PUT operation, and to 
check the file status, in a 
multitasking environment: 

1 . Open 

2. Transmit error 

3. Invalid 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(DCLCB) 

A (Abnormal return) 

Called by: Compiled code 



Entry point IHEIBTB 

Function: 

To initialize PUT, and perform PAGE, 
and to check the file status, in a 
multitasking environment: 

1 . Open 

2. Transmit error 

3. Invalid 

Linkage: As for IHEIBTA 

Called by: Compiled code 

Entry point IHEIBTC 

Function: 

To initialize PUT, and perform SKIP, 
and to check the file status, in a 
multitasking environment: 

1 . Open 

2. Transmit error 

3. Invalid 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(DCLCB) 

A (Abnormal return) 

A (Expression value) 

Called by: Compiled code 

Entry point IHEIBTD 

Function: 

To initialize PUT, and perform LINE, 
and to check the file status, in a 
multitasking environment: 



1. Open 

2. Transmit error 

3. Invalid 



Linkage: As for IHEIBTC 
Called by: Compiled code 

Entry point IHEIBTE 

Function : 

To initialize PUT, and perform PAGE and 
LINE, and to check the file status, in 
a multitasking environment: 

1 . Open 

2. Transmit error 

3. Invalid 

Linkage: As for IHEIBTC 
Called by: Compiled code 

Entry point IHEIBTT 

Function: 

To terminate the PUT operation, in a 
multitasking environment. 

Linkage: None 

Called by: Compiled code 

IHEIGT 

Entry point: IHEIGTA 

Function: 

As for IHEINT 

IHEINT 

This module is used in a multitasking 
environment and is equivalent to module 
IHEION in a non-multitasking environment. 

Calls: 

Supervisor (CHAP, FREEMAIN, GETMAIN) , 

IHEITB, IHEITC, IHEITD, IHEITE, IHEITF, 
IHEIG, IHEIH, IHEIJ, IHEITP, IHEOCT 

Entry point: IHEINTA 

Function: 

To verify a RECORD I/O request and to 
invoke the appropriate data management 
interface module to perform the required 
operation, in a multitasking environment. 
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Linkage: 



Linkage: 



RA: A (Parameter list) 
Parameter list: 

A(DCLCB) 

A (RDV)/ (IGNORE factor) 

A(EVENT variable)/ (0)/A(Error return) 

A(KEY|KEYFROM|KEYTO SDV)/(0) 

A (Request control block) 



Called by: Compiled code 

IHEIOA 

Calls: IHEIOP, IHEOCL, IHEOCT 

Entry point IHEIOAA 

Functions 

To initialize the GET operation, and to 
check the file status: 

1 . Open 

2. Endfile 

3. Invalid 



Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(DCLCB) 

A (Abnormal return) 

Called by: Compiled code 



Entry point IHEIOAB 

Function: 

To initialize the GET operation, with 
the COPY option, and to check the file 
status : 

1 . Open 

2. Endfile 

3 . Invalid 

Linkage: As for IHEIOAA 

Called by: Compiled code 

Entry point IHEIOAC 

Function: 

To initialize the GET operation with 
the SKIP option, and to check the file 
status: 

1. Open 

2. Endfile 

3 . Invalid 



RA: A (Parameter list) 

Parameter list: 
A(DCLCB) 

A (Abnormal return) 
A (Expression value) 



Called by: Compiled code 
Entry point IHEIOAT 

Function: 

To terminate the GET operation. 

Linkage: None 

Called by: Compiled code 
IHEIOB 
Calls: 

IHEIOP, IHEOCL 
Entry point IHEIOBA 

Function: 

To initialize the POT operation, and to 
check the file status: 

1. Open 

2. Transmit error 

3. Invalid 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(DCLCB) 

A (Abnormal return) 

Called by: Compiled code 

Entry point IHEIOBB 

Function: 

To initialize POT, and perform PAGE, 
and to check the file status: 

1. Open 

2. Transmit error 

3. Invalid 

Linkage: As for IHEIOBA 

Called by: Compiled code 

Entry point IHEIOBC 

Function: 

To initialize PUT, and perform SKIP, 
and to check the file status: 
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1 . Open 

2. Transmit error 

3. Invalid 



Linkage: 

RA: A (Parameter list) 

Parameter list: 
A(DCLCB) 

A ( Abnormal return) 
A (Expression value) 

Called by: Compiled code 



Entry point IHEIOBD 

Function: 

To initialize PUT, and perform LINE, 
and to check the file status: 

1 . Open 

2. Transmit error 

3. Invalid 

Linkage: As for IHEIOBC 
Called by: Compiled code 

Entry point IHEIOBE 

Function: 

To initialize POT, and perform PAGE and 
LINE, and to check the file status: 

1 . Open 

2. Transmit error 

3. Invalid 

Linkage: As for IHEIOBC 

Called by: Compiled code 
Entry point IHEIOBT 

Function: 

To terminate the PUT operation. 

Linkage: None 

Called by: Compiled code 
IHEIOC 

Calls: IHESAP, IHETSA 
Entry point IHEIOCA 

Function: 

To initialize the GET operation, with 
the STRING option. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(SDV) 

A (DEO) 

Called by: Compiled code 

Entry point IHEIOCB 

Function: 

To initialize the GET operation, with 
the STRING and COPY options. 

Linkage: As for IHEIOCA 

Called by: Compiled code 

Entry point IHEIOC C 

Function: 

To initialize the PUT operation, with 
the STRING option. 

Linkage: As for IHEIOCA 

Called by: Compiled code 

Entry point IHEIOCT 

Function: 

To terminate the GET or PUT operations, 
with the STRING option. 

Linkage: None 

Called by: Compiled code 

IHEIOD 

Calls: IHEIOF, IHESAP, IHEPRT, IHEPTT, 
IHETSA 

Entry point IHEIODG 

Function : 

To obtain the next data field from the 
record buffer (s).. 

Linkage: 

Library communication area (WSDV) 

Called by: Format directors, IHEIOX 

Entry point IHEIODP 

Function: 

To obtain space for a data field in the 
record buffer(s). 

Linkage: As for IHEIODG 



110 



Called by: Format directors, I HE I OX 
Entry point IHEIODT 

Function: 

To terminate the data field request. 

Linkage: As for IHEIODG 

Called by: Format directors 

IHEIOF 

Calls: Data management (QSAM) 

Entry point: IHEIOFA 

Function: 

To obtain logical records via data 
management interface modules, and 
initialize FCB record pointers and 
counters . 

Linkage: RA: A(FCB) 

Called by: 

IHEDDI. IHEDDO, IHEDDT, IHEIOD, IHEIOP, 
IHEIOX, IHELDI, IHELDO, IHEOCL, IHEOCT, 
IHEPRT, IHEPTT 

IHEIOG 

Entry point: IHEIOGA 

Function: 

As for IHEION 

IHEION 

This module is used in a 
non-multitasking environment and is 
equivalent to module IHEINT in a 
multitasking environment. 

Calls: 

Supervisor (FREEMAIN, GETMAIN), IHEITB, 
IHEITC, IHEITD, IHEITE, IHEITF, IHEITG, 
IHEITP, IHEOCL 

Entry point: IHEIONA 

Function: 

To verify a RECORD I/O request and to 
invoke the appropriate data management 
interface module to perform the required 
operation, in a non-multitasking 
environment. 

Linkage: 

RA: A (Parameter list) 



Parameter list: 
A(DCLCB) 

A (RDV)/( IGNORE factor) 
A (EVENT variable)/ (0) /A (Error return) 
A(KEY|KEYFROM|KEYTO SDV)/(0) 
A (Request control block) 



Called by: Compiled code 
IHEIOP 

Calls: IHEIOF 
Entry point IHEIOP A, 

Function: PAGE option/ f ormat . 

Linkage: No explicit parameters 

Called by: Compiled code, IHEIOB, IHEIBT 
Entry point IHEIOPB 

Function: SKIP option/ f ormat . 

Linkage: 

RA: A (FED) 

FED: Half word binary integer 

Called by: Compiled code, IHEIOA, IHEIOB, 
IHEIBT 

Entry point IHEIOPC 

Function: LINE option/format. 

Linkage: As for IHEIOPB 

Called by: As for IHEIOPA 
IHEIOX 

Calls: IHEIOD, IHEIOF 
Entry point IHEIOXA 

Function: 

To skip next n characters in record (s). 

Linkage: 

RA: A (FED) 

FED: Half word binary integer 

Called by: Compiled code 

Entry point IHEIOXB 

Function: 

To place n blanks in record (s) . 

Linkage: As for IHEIOXA 

Called by: Compiled code 
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Entry point IHEIOXC 

Function: To position to COLUMN (n). 

Linkage: As for IHEIOXA 

Called by: Compiled code 

IHEITB 

Calls: 

Data management (BSAM), Supervisor (CHAP, 
GET MAIN) 

Entry point: IHEITBA 

Function: 

To provide the interface with BSAM for: 

1. CONSECUTIVE data sets with the 
UNBUFFERED attribute. 

2. REGIONAL data sets, whether or not 
UNBUFFERED, opened for INPUT/UPDATE 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(IOCB)/A(IGNORE f actor)/A(SDV) 

A (Event variable)/ (0) 

A ( KEY | KE YFROM | KEYTO SD V) / ( ) 

A (Request control block) 

Called by: IHEION, IHEINT 

IHEITC 

Calls: 

Data management (BSAM), Supervisor (CHAP, 
GETMAIN) 

Entry point: IHEITCA 

Function: 

To provide the interface with BSAM for 
creating REGIONAL data sets when opened 
for SEQUENTIAL output. 

Linkage: 

RA: A(FCB) 

RB: A(Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(IOCB) 

A (Event variable)/ (0)/A(Abnormal 
return) 

A(KEY|KEYFROM SDV)/(0) 

A (Request control block) 

Called by: IHEION, IHEINT, IHEOCL, IHEOCT 



IHEITD 

Calls: 

Data management (QISAM), Supervisor 
(GETMAIN), IHESAP, IHETSA 

Entry point: IHEITD A 



Function: 

To provide the interface with QISAM for 
creating or accessing fixed length record 
INDEXED data sets when opened for 
SEQUENTIAL access. 

Linkage: 

RA: A(FCB) 

RB: A(Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(SDV) 

A (Error return) /(0) 

A(KEY|KEYFROM|KEYTO SDV)/(0) 

A (Request control block) 

Called by: IHEION, IHEINT 

IHEITE 

Calls: 

Data management (BIS AM), Supervisor 
(GETMAIN), IHESAP 

Entry point: IHEITE A 

Function: 

To provide the interface with BISAM for 
accessing fixed length record INDEXED 
data sets opened for DIRECT access in a 
non- mult it asking environment. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(IOCB)/A(SDV) 

A(Event variable)/ (0) 

A(KEY|KEYFROM SDV)/(0) 

A (Request control block) 

Called by: IHEION, IHEOSW 

IHEITF 

Calls: 

Data management (BDAM), Supervisor 
(GETMAIN), IHESAP 

Entry point: IHEITFA 
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Function: 

To provide the interface with BDAM for 
REGIONAL data sets opened for DIRECT 
access in a non-multitasking environment. 



Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 
A(DCLCB) 

A(RDV)/A(IOCB)/A(SDV) 
A (Event variable)/ (0) 
A(KEY|KEYFROM SDV)/(0) 
A (Request control block) 



Called by: IHEION 

IHEITG 

Calls: Data management (OS AM) 

Entry point: IHEITGA 

Function: 

To provide the interface with QSAM for 
CONSECUTIVE data sets opened for RECORD 
I/O with the BUFFERED attribute. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(SDV) 

A (Error return)/ (0) 

A(0) 

A (Request control block) 

Called by: IHEION, IHEINT 

IHEITH 

Calls: 

Data management (BISAM), Supervisor 
(CHAP, DEQ, ENQ, GETMAIN), IHETSA 

Entry point: IHEITHA 

Function: 

To provide the interface with BISAM for 
accessing fixed length record INDEXED 
data sets opened for DIRECT access in a 
multitasking environment. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 



Parameter list: 
A(DCLCB) 

A ( RDV) /A ( IOCB) /A ( SDV) 
A (Event variable) /(0) 
A (KEY | KEYFROM SDV)/(0) 
A (Request control block) 



Called by: IHEINT, IHETSW 



IHEITJ 
Calls: 

Data management (BDAM), Supervisor (CHAP, 
DEQ, ENQ, GETMAIN), IHETSA 

Entry point: IHEITJ A 

Function: 

To provide the interface with BDAM for 
REGIONAL data sets opened for DIRECT 
access in a multitasking environment. 

Linkage : 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(IOCB)/A(SDV) 

A (Event variable)/ (0) 

A (KEY | KEYFROM SDV) /(0) 

A (Request control block) 

Called by: IHEINT 

IHEITK 

Calls: 

Data Management (QSAM) , Supervisor 
(GETMAIN, FREEMAIN) 

Entry point: IHEITKA 

Function: 

To provide the interface with QSAM for 
consecutive data sets opened for RECORD 
I/O Input with the BUFFERED attribute and 
VS or VBS format records. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A (RDV) /A (SDV) 

A (Error Return) /(0) 

A(0) 

A (Request Control Block) 

Called by: IHEION, IHEINT 
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IHEITL 



Linkage : 



Calls: 



Data Management (QSAM) , Supervisor 
(GETMAIN, FREEMAIN) 



Entry point: IHEITLA 



Function: 

To provide the interface with QSAM for 
consecutive data sets opened for RECORD 
I/O Output with the BUFFERED attribute 
and VS or VBS format records. 



Linkage: as for IHEITK 

Called by: IHEION, IHEINT, IHEOCL 

IHEITM 

Calls: 

Data management (BISAM), Supervisor 
(GETMAIN), IHESAP 

Entry point: IHEITMA 

Function: 

To provide the interface with BISAM for 
accessing variable length record INDEXED 
data sets opened for DIRECT access in a 
non-multitasking environment. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(IOCB)/A(SDV) 

A (EVENT variable)/ (0) 

A(KEY|KEYFROM SDV)/(0) 

A (Request control block) 

Called by: IHEION, IHEOSW 

IHEITN 

Calls: 

Data management (QISAM), Supervisor 
(GETMAIN), IHESAP, IHETSA 

Entry point: IHEITNA 

Function: 

To provide the interface with QISAM for 
creating or accessing variable length 
record INDEXED data sets when opened for 
SEQUENTIAL access. 



RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(SDV) 

A (Error return) /(0) 

A(KEY|KEYFROM|KEYTO SDV)/(0) 

A (Request control block) 

Called by: IHEION, IHEINT 



IHEITO 

Calls: 

Data management (BISAM), 

SUPERVISOR (CHAP, DEQ, ENQ, GETMAIN) , IHETSA 



Entry point: IHEITOA 



Function: 

To provide the interface with BISAM for 
accessing variable length record INDEXED 
data sets opened for DIRECT access in a 
multitasking environment. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(IDCB)/A(SDV) 

A(EVENT variable)/ (0) 

A(KEY|KEYFROM SDV)/(0) 

A (Request control block) 

Called by: IHEINT, IHETSW 

IHEITP 

Calls: Data management (QTAM) 

Entry point: IHEITP A 

Function: 

To provide the interface with QTAM for 
teleprocessing files opened for record 
I/O. 

Linkage: 

RA: A(FCB) 

RB: A (Parameter list) 

Parameter list: 

A(DCLCB) 

A(RDV)/A(SDV) 

A (Error return) /(0) 

A (KEY SDV) 

A (Request control block) 

Called by: IHEION, IHEINT 
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IHEJXI 

Calls: IHESAP, IHETSA 

Entry point IHEJXI I 

Function: 

To initialize IHEJXI to give bit 
addresses, and to find the first 
element of the array. 

Linkage: 

RA: A(ADV) 

RB: A (Number of dimensions) 

On return: 

RA: Bit address of first element 

Called by: IHENL2, IHESTG 

Entry point IHEJXIY 
Function: 

As for IHEJXI I but for byte addresses. 

Linkage: 

RA: A(ADV) 

RB: A (Number of dimensions) 

On return: 

RA: A (First element) 

called by: 

IHEOSW, IHEPDF, IHEPDL, IHEPDS, IHEPDW, 
IHEPDX, IHEPDZ, IHESMF, IHESMG, IHESMH, 
IHESMX, IHESTG, IHETSW 

Entry point IHEJXI A 

Function: 

To find the next element of the array. 

Linkage: 

No explicit arguments 
Implicit arguments: 
LCA 

VDA, obtained in initialization 
On return: 
RA: Bit or byte address of the next 

element 
BR=0: Normal return 
BR=U: If the address of the last 

element of the array was provided 
on the previous normal return 

Called by: 

All modules calling IHEJXII and IHEJXIY 



IHEJXS 

Entry point IHEJXSI 

Function: 

To find the first and last elements of 
an array and to give their addresses as 
bit addresses. 

Linkage: 

RA: A(ADV) 

RB: A (Number of dimensions) 

On Return : 

RO: Bit address of first element 

RA: Bit address of last element 

Called by: IHENLl 

Entry point IHEJXSY 

Function: 

As for IHEJXSI but for byte addresses. 

Linkage: 

RA: A(ADV) 

RB: A( Number of dimensions) 

On return: 

RO: A( First element) 

RA: A (La st element) 

Called by: 

IHEPSF, IHEPSL, IHEPSS, IHEPSW, IHEPSX, 
IHEPSZ, IHESSF, IHESSG, IHESSH, IHESSX. 
IHENLl, compiled code for 
initialization purposes 

IHEKCA 

Entry point: IHEKCAA 

Function: 

To check that external data with a 
decimal picture specification is valid 
for that specification. 

Linkage: 

RA: A (Source) 
RB: A (Source DEO) 

Called by: IHEDIE, IHEDIM 

IHEKCB 

Entry point: IHEKCB A 

Function: 

To check that external data with a 
sterling picture specification is valid 
for that specification. 
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Linkage: 

RA: A (Source) 
RB: A( Source DED) 

Called by: IHEDIE 



IHEKCD 

Entry point IHEKCDA 

Function: 

To check that external data with a 
character picture specification is 
valid for that specification. The 
ONSOURCE address is stored. 

Linkage: 

RA: A (Source) 
RB: A (Source DED) 

Called by: IHEDIB 

Entry point IHEKCDB 

Function: 

As for IHEKCDA, but the ONSOURCE 
address is not stored. 

Linkage: As for IHEKCDA 

Called by: IHELDI 

IHELDI 

Calls: 

IHEDCN, IHEDMA, IHEDNB, IHEDNC, IHEIOF, 

IHEKCD, IHEPRT, IHEPTT, IHESAP, IHETSA, 

IHEUPA, IHEUPB, IHEVCA, IHEVCS, IHEVSC, 
IHEVSD 

Entry point IHELDIA 

Function: 

To read data from an input stream and 
to assign it to internal variables 
according to list-directed input 
conventions. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Variablei.) 

A (DED*) 



A(Variable n ) 
A(DEDn) 

(High-order byte of last argument 
indicates end of parameter list.) 



Called by: Compiled code 

Entry point IHELDI B 

Function: 

As for IHELDIA but for single 
variables. 



Linkage: 

RA: A( Variable) 
RB: A(DED) 

Called by: Compiled code 



Entry point IHELDIC 

Function: 

To scan the value field (entry for 
data-directed input) . 

Linkage: 

RA: A (Buffer SDV) 

RB: A (Control block) 

Control block: H'VDA count so far* 

X'Flag box* (one byte) 
Return codes: 

BR=0: Not last item 
BR=t: Last item 

BR-8: End of file encountered before 
complete data field collected 

Called by: IHEDDI 

Entry point IHELDI D 

Function: 

To assign a value to a variable (entry 
for data-directed input) . 

Linkage: 

RA: A( Variable) 

RB: A (DED) 

RC: A( Control block) 

Control block: H'VDA count so far' 

X'Flag box' (one byte) 

Called by: IHEDDI 
IHELDQ 

Calls: IHEDNC, IHEIOF, IHEVSB, IHEVSC 
Entry point IHELDOA 

Function: 

To prepare data for output according to 
list-directed output conventions, and 
to place it in an output stream. 
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Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Variable,) 

A(DED,) 



A(Variable n ) 
A(DED n ) 

(High-order byte of last argument 
indicates end of parameter list.) 



Called by: Compiled code, IHEDDT 

Entry point IHELDOB 

Function: 

As for IHELDOA, but for only one item 
of the list of data. 

Linkage: 

RA: A (Variable) 
RB: A(DED) 

Called by: Compiled code, IHEDDT 

Entry point IHELDOC 

Function: 

As for IHELDOA, but used by 
data- directed output. 

Linkage: 

RA: A (Variable) 
RB: A(DED) 
RC: A(FCB) 

Called by: IHEDDO, IHEDDT 
IHELNL 
Entry point IHELNLE 

Function: 

LOG(x), where x is real long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called fcy: 

Compiled code, IHEHTL, IHELNZ, IHEXXL, 
IHEXXZ 



Entry point IHELNL2 

Function: 

L0G2(x), where x is real long 
floating-point. 

Linkage: As for IHELNLE 

Called by: As for IHELNLE 

Entry point IHELNLD 

Function : 

LOG10(x), where x is real long 
floating-point. 

Linkage: As for IHELNLE 

Called by: As for IHELNLE 
IHELNS 
Entry point IHELNSE 

Function : 

LOG(x), where x is real short 
floating-point. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 
A(x) 

A (Target) 

Called by: 

Compiled code, IHEHTS, IHELNW, IHEXXS, 
IHEXXW 

Entry point IHELNS2 

Function: 

LOG2(x), where x is real short 
floating-point . 

Linkage: As for IHELNSE 

Called by: As for IHELNSE 

Entry point IHELNSD 

Function : 

LOG10(x), where x is real short 
floating-point. 

Linkage: As for IHELNSE 

Called by: As for IHELNSE 
IHELNW 
Calls: IHEATS, IHELNS 
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Entry point: IHELNWO 

Function: 

LOG(z), where z is complex short 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code, IHEXXW 

IHELNZ 

Calls: IHEATL, IHELNL 

Entry point: IHELNZO 

Function: 

LOG(z), where z is complex long 
f loa ting-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code, IHEXXZ 

IHELSP 

Calls: Supervisor (FREEMAIN,GETMAIN) 

Function: 

Storage management for list processing. 
Entry point IHELSP A 

Function: 

To provide storage in an area variable 
for an allocation of a based variable. 

Linkage: 

RA: A (Eight- byte word-aligned parameter 

list) 
RB: A (ALLOCATE statement) 
Parameter list: 
Byte 0: Not used 
Bytes 1-3: A (Area variable) 
Byte 4: Offset of beginning of based 
variable from doubleword 
boundary 
Bytes 5-7: Length of based variable 

On return: 



RA: A (Eight-byte word-aligned parameter 
list) 



Parameter list: 
Byte 0: Not used 
Bytes 1-3: A( Based variable) 
Byte 4: Offset of beginning of based 

variable from doubleword 

boundary 
Bytes 5-7: Length of based variable 



Called by: Compiled code 

Entry point IHELSPB 

Function: 

To free storage allocated to a based 
variable in an area variable. 

Linkage: 

RA: A( Eight- byte word-aligned parameter 

list) 
RB: A(Area variable) 
Parameter list: 
Byte 0: Not used 
Bytes 1-3: A( Based variable) 
Byte 4: Offset of beginning of based 
variable from doubleword 
boundary 
Bytes 5-7: Length of based variable 

Called by: Compiled code 

Entry point IHELSPC 

Function: 

Assignments between area variables. 

Linkage: 

RA: A(Source area variable) 
RB: A( Target area variable) 

Called by: Compiled code. 

Ent ry point IHELSPD 

Function: 

To provide system storage for an 
allocation of a based variable (using 
GETMAIN macro) . . 

Linkage: 

RA: A( Eight-byte word-aligned parameter 
list) 

Parameter list: 

Bytes 0-3: Not used 

Byte 4: Offset of beginninq of based 
variable from doubleword 
boundary 

Bytes 5-7: Length of based variable 
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On return; 

RA: A (Eight"- byte word- aligned parameter 

list) 
Parameter list: 

Byte 0: Hot used 

Bytes 1-3: A(Based variable) 

Bytes 4-7: Not used 

Called by: Compiled code 



Entry point IHELSPE 



Function: 



To free system storage allocated to a 
based variable (using FREEMAIN macro). 



Linkage : 

RA: A (Eight-byte word-aligned parameter 
list) 

Parameter list: 
Byte 0: Not used 
Bytes 1-3: A (Based variable) 
Byte 4: Offset of beginning of based 

variable from doubleword 

boundary 
Bytes 5-7: Length of based variable 

Called by: Compiled code 



Entry point IHELTTB 

Function: 

Stores the addresses of the pseudo 
entry points of the transfer vector 
modules IHELTTA and IHELTVA in the PRV. 
(see * below) 

Called by: IHESAP/IHETSA 

Entry point IHELTTC 

Function: 

Deletes library module IHELTVA if this 
was loaded and returns to the operating 
system. 

Called by: 

compiled code (on completion of PL/ I 
program) 

♦ Pseudo Entry points : IHELTTl, IHELTT2, 
IHELTT3, IHELTT4, IHELTT5 

Function: 

These act as reference points for the 
transfer vector tables when control is 
passed between the resident library 
modules and the partition. 

IHELTV 



IHELTT 

Calls: IHESAP, IHETSA, compiled code, 
operating system 

Function: 

This module is the transfer vector 
table which is link-edited to the PL/I 
program when the shared Library feature 
is selected. It formats the standard 
section of the PRV and is responsible 
for ensuring the correct entry to the 
PL/I program from the operating system. 
It also sets the address of the 
transfer vector tables into the first 
pseudo-register of the PRV- 

Entry point IHELTTA 

Function: 

Main entry point from operating system. 
Loads library module IHELTVA if this is 
not already resident and determines 
address of IHELTVA. 

Calls: IHESAP/IHETSA 

Called by: operating system 



Function: 

Transfer vector table link-edited to 
the resident library modules when 
shared library feature is selected. 
Formats standard section of PRV and 
locates transfer vector table pseudo 
entry points. 

Called by: IHELTT 

Entry point IHELTV A 

Function: 

Contains addresses of pseudo entry 
points (♦see below) in first twenty 
bytes. 

Called by: IHELTT 

♦ Pseudo Entry Points: IHELTV1, IHELTV2, 
IHELTV3, IHELTV4, IHELTV5 

Function: as for IHELTT. 



IHEM91 



Calls: IHEERR 
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Entry point IHEM91A 
Function: 

1. To analyze the exception or 
exceptions in an imprecise interrupt 
on Models 91 and 195 

2. To set up a list of these exceptions 
(in LWE) 

3. To raise the first of a series of 
PL/I conditions corresponding to 
these exceptions 

Linkage: 

PSW at interrupt is in current 
LWE + 112 

Called by: 

IHEERR, when an imprecise interrupt is 
detected 

Entry point IHEM91B 

Function: 

To continue raising, in succession, the 
PL/I conditions corresponding to the 
exceptions. 

Linkage: 

List of exceptions is in current 
LWE ♦ 136 

Called by: IHEERR 

Entry point IHEM91C 

Function: 

To print an error message for each 
unprocessed exception when, as a result 
of the processing of an earlier 
exception in the list, a program is 
forced to terminate before processing 
of the list is complete. 

Linkage: None 

Called by: IHEERR 

IHEMAI 

Entry point: IHEMAIN 

Function: 

Contains address of IHEBEGN; loaded only 
if there is no main procedure. 

Linkage: None 



Called by: IHESAP, IHETSA 

IHEMPU 

Entry point: IHEMPOO 

Function: 

MULTIPLY (w,z,p,g) , where w and z are 
complex fixed binary, and (p,q) is the 
target precision. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(w) 

A(DED for w) 

A(z) 

A(DED for z) 

A(Target) 

A (DEO for target) 

Called by: Compiled code 



IHEMPV 

Calls: IHEAPD 

Entry point: IHEMPVO 

Function: 

MULTIPLY (w,z,p,g) , where w and z are 
complex fixed decimal, and (p,q) is the 
target precision. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(w) 

A(DED for w) 

A(z) 

A(DED for z) 

A (Target) 

A(DED for target) 

Called by: Compiled code 

IHEMSI 

Entry point: IHEMSIA 

Function: 

To call IHEERRC so that an error message 
is printed saying that STIMER facilities 
are unavailable. 

Called by: compiled code 

IHEMST 

Entry Point: IHEMSTA 
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Function: 

To call IHEERRC so that an error message 
is printed saying that the TIME facility 
is unavailable. 



Called by: Compiled code 



I HEMS W 



Calls: 



Supervisor (FREEMAIN, WAIT), I/O transmit 
module whose address is in the FCB. 



Entry point: IHEMSWA 

Function: 

1. According to the count passed, to 
return to the caller or to wait until 
a single I/O event is complete. If 
the count is <0, immediate return is 
made; otherwise the event is waited 
on. 

2. To branch to the I/O transmit module 
to raise I/O conditions if necessary. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Count) 

A (Event variable) 

Called by: Compiled code 

IHEMXB 

Entry point IHEMXBX 

Function: 

MAX(x A ,x a , . . . ,x n )# where x lf x a and x n 
are real fixed- point binary. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x t ) 

A(DED for x x ) 



A(x n ) 

A (DEO for x n ) 
A (Target) 
A (Target DED) 

(High-order byte of last argument 
indicates end of parameter list.) 

Called by: Compiled code 



Entry point IHEMXBN 

Function: 

MlN(x lf x 2 » . . . i x n )» where x 1( x 2 and x n 
are real fixed-point binary. 

Linkage: As for IHEMXBX 
Called by: Compiled code 

IHEMXD 

Ent ry point IHEMXDX 

Function: 

MAX(x lf x 2 , . . . ,x n ) , where x lr x 2 and x n 
are real fixed-point decimal. 



Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(Xj.) 

A (DED for Xa.) 



A(x n ) 

A (DED for x n ) 
A(Target) 
A (Target DED) 

(High-order byte of last argument 
indicates end of parameter list.) 



Called by: Compiled code 



Ent ry p oin t IHEMXDN 



Function: 

MIN(x 1 ,x 2 . . . , x n ) i where Xj.,x 2 and x n 
are real fixed-point decimal. 



Linkage: As for IHEMXDX 
Called by: Compiled code 

IHEMXL 

Entry point IHEMXLX 



Function: 

MAX (x x ,x 2 , . . . ,x n ) , where x 1# x 2 and x n 
are real long floating-point. 
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Linkage: 



IHEMZU 



RA: A (Parameter list) 
Parameter list: 

A(x-,) 

A(x 2 ) 



A(x n ) 

A(Target) 

(High-order byte of last argument 
indicates end of parameter list. ) 

Called by: Compiled code 

Entry point IHEMXLN 

Function: 

MIN(xi ,x 2/ . • • #x n ) r where x,,x 2 and x n 
are real long floating-point. 

Linkage: As for IHEMXLX 

Called by: Compiled code 

IHEMXS 

Entry point IHEMXSX 

Function: 

MAX(x-, ,x 2 , . . . ,x n ) , where x,,x 2 and x n 
are real short floating-point. 

Calls: IHEJXS 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x,) 

A(x 2 ) 



A(x n ) 
A (Target) 

(High-order byte of last argument 
indicates end of parameter list.) 

Called by: Compiled code 

Entry point IHEMXSN 

Function: 

MIN(x 1f x 2 , .. . , x n )» where x-,,x 2 and x n 
are real short floating-point. 

Linkage: As for IHEMXSX 

Called by: Compiled code 



Entry point IHEMZUM 

Function : 

Zi*z 2r where 7.^ and z 2 are complex 
fixed- point binary. 



mka 


ge: 


RA: 


A(z-,) 


*RB: 


A(DED for z„) 


RC: 


A(z 2 ) 


*RD: 


A(DED for z 2 ) 


RE: 


A( Target) 


*RF: 


A (Target DED 



Called by: Compiled code, IHEXIU 

Entry point IHEMZUD 

Function: 

z 1 /z 2r where z, and z 2 are complex 
fixed- point binary. 



Linkage: 




RA: 


A(z,) 




RB: 


A(DED for 


z,) 


RC: 


A(z 2 ) 




*RD: 


A(DED for 


z 2 ) 


RE: 


A(Target) 




*RF: 


A (Target 


DED) 



Called by: Compiled code 
IHEMZV 
Entry point IHEMZVM 

Function: 

Zi*z 2 , where Zi and z 2 are complex 
fixed-point decimal. 

Linkage: 

RA: A(z^) 
RB: A(DED for z,) 
RC: A(z 2 ) 
RD: A(DED for z 2 ) 
RE: A( Target) 
*RF: A(Target DED) 

Called by: compiled code, IHEXIV 

Entry point IHEMZVD 

Function: 

z,/z 2 , where z^ and z 2 are complex 
fixed- point decimal. 

Linkage: As for IHEMZVM 

Called by: Compiled code 
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IHEMZW 



Linkage: 



Entry point: IHEMZWO 

Function: 

Zj.*z a » where z ± and z a are complex short 
floating-point . 

Linkage: 

RA: A(z x ) 
RB: A(z a ) 
RC: A (Target) 

Called by: Compiled code,IHEXIW 

IHEMZZ 

Entry point: IHEMZZO 

Function: 

z ± *z a , where z x and z a are complex long 
floating-point. 

Linkage: 

RA: A(Zj.) 
RB: A(z a ) 
RC: A (Target) 

Called by: Compiled code,IHEXIZ 

IHENLl 

Calls: IHEJXS 

Entry point IHENLlA 

Function: 

ALL or ANY for a simple array (or an 
interleaved array of VARYING elements) 
of byte-aligned elements and a 
byte- aligned target. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 
A(SADV) 

A (Number of dimensions) 
A(DED of the array) 
(A(IHEBSAO) for ALL, or 
(A(IHEBSOO) for ANY 
A(SDV for Target field ) 

Called by: Compiled code 

Entry point IHENLlL 

Function: 

ALL for a simple array (or an 
interleaved array of VARYING elements) 
of elements with any alignment, and a 
target with any alignment. 



RA: A (Parameter list) 
Parameter list: 

A(SADV) 

A (Number of dimensions) 

A(DED of the array) 

A(IHEBSFO) 

MSDV for target field ) 

Called by: Compiled code 



Entry point IHENL1 N 

Function: As for IHENLlL, but ANY. 

Linkage: As for IHENLlL 
Called by: Compiled code 

IHENL2 

Calls: IHEJXI 

Entry point IHENL2A 

Function: 

ALL or ANY for an interleaved array of 
fixed- length byte- aligned elements and 
a byte-aligned target. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 
A(SADV) 

A (Number of dimensions) 
*A(DED of the array) 
(A(IHEBSAO) for ALL, or 
(A(IHEBSOO) for ANY 
A(SDV for target field) 

Called by: Compiled code 

Entry point IHENL2L 

Function: 

ALL for an interleaved array of 
fixed- length elements with any 
alignment, and a target with any 
alignment. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(SADV) 

A (Number of dimensions) 
*A(DED of the array) 

A(IHEBSFO) 

A(SDV for target field) 

Called by: Compiled code 
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Entry point IHENL2N 

Function: 

ANY for an interleaved array of 
fixed-length elements with any 
alignment, and a target with any 
alignment. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(SADV) 

A (Number of dimensions) 
*A(DED of the array) 

A(IHEBSFO) 

A(SDV for target field) 

Called by: Compiled code 

IHEOCL 

Calls : 

Supervisor (DCBD, FREEMAIN, LINK) , IHECLT, 
IHEIOF, IHEITC, IHEITL, IHEOPN, IHESAP 

Entry point IHEOCLA 

Function: 

Explicit open: links to IHEOPNA; 
handles error conditions detected by 
IHEOPN, IHEOPO, IHEOPP, IHEOPQ or 
IHEOPZ. 

Linkage: 

RA: A (OPEN parameter list) 
Parameter list: See IHEOPN 

Called by: Compiled code, IHEPRT 

Entry point IHEOCLB 

Function : 

Explicit close: links to IHECLTA. 

Linkage: 

RA: A (CLOSE parameter list) 
Parameter list: See IHECLTA 

Called by: Compiled code 

Entry point IHEOCLC 

Function: 

To perform implicit open. 

Linkage: 

RA: A(OCB) 
RB: A(DCLCB) 



Called by: IHEIOB, IHEION, IHESAP 

Entry point IHEOCLD 

Function: 

Implicit close: 

1. When a task is terminated, to close 
all the files opened in the task 
(by linking to IHECLTB). 

Linkage: 

RA: A(PRV of current task) 

Called by: IHESAP 

IHEOCT 

Calls: 

Supervisor (DCBD, DEQ, FREEMAIN, LINK), 
IHECTT, IHEIOF, IHEITC, IHEITL, IHEOPN, 
IHETSA 

Entry point IHEOCTA 

Function: 

Explicit open in a multitasking 
environment: links to IHEOPNA; handles 
error conditions detected by IHEOPN, 
IHEOPO, IHEOPP, IHEOPQ or IHEOPZ. 

Linkage: 

RA: A (OPEN parameter list) 
Parameter list: See IHEOPN 

Called by: Compiled code, IHEPTT 

Entry point IHEOCTB 

Function: 

Explicit close in a multitasking 
environment: links to IHECTTA. 

Linkage: 

RA: A (CLOSE parameter list) 
Parameter list: See IHECTTA 

Called by: Compiled code 

Entry point IHEOCT C 

Function: 

To perform implicit open in a 
multitasking environment. 

Linkage: 

RA: A(OCB) 
RB: A(DCLCB) 
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Called by IHEIBT, IHEINT, IHETSA 
Entry point IHEOCTD 

Function: 

Implicit close: 



OPEN Parameter list: 
A(DCLCBa.) 

A (OPEN Control blockj.)/0 
A(TITLE-SDV i )/0 
(Reserved) 
(Reserved) 
(Reserved) 
A(LINESIZEi)/0 
A(PAGE3IZEi.)/0 



1. When a task is terminated, to close 
all the files opened in the task 
(by linking to IHECTTB). 



2. To dequeue all records locked by 

the task and free the corresponding 
EXCLUSIVE blocks. 



To set all imcomplete EVENT 
variables complete, inactive, and 
abnormal, and to free the 
associated IOCBs. 



Linkage: 



A(DCLCBn) 

A (OPEN Control block n )/0 
A(TITLE-SDV n )/0 
(Reserved) 
(Reserved) 
(Reserved) 
A(LINESIZE n )/0 
A(PAGESIZE n )/0 

(High- order byte of last argument 
indicates end of parameter list.) 

Called by: IHEOCL, IHEOCT 



IHEOPO 
Calls: 

Supervisor (DCB,DCBD,DEVTYPE,GETMAIN) , 
IHEOPP (via XCTL), IHESAP, IHETSA 



RA: A(PRV of current task) 



Entry Point: IHEOPOA 



Called by: IHETSA 

IHEOPN 

Calls: 

IHEOPO (via XCTL), IHEOPZ (via LINK), 
IHESAP, IHETSA 

Entry point: IHEOPNA 



Function: 

Open files: 

1. Merge declared attributes with OPEN 
options. 

2. Invoke IHEOPO. 

3. Invoke IHEOPZ if declared DIRECT 
OUTPUT (REGIONAL (1), (2) and (3) 
only). 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (OPEN Parameter list) 

A (Private Adcons) 



Function: 

1. To create and format the FCB. 

2. To set file register to A (FCB). 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

A (IHEOPN Parameter list) 

A(subparameter list) 
Subparameter list: 

XL4*4*n' (where n is the number of files 
to be opened) 

X* Access/Organization Code*' 

AL3(DCLCB X ) 

XL**' Merged attribute*.' 



X* Access/Organization Code n * 

AL3(DCLCBn) 

XL4' Merged attribute,/ 

NOTE: Access/Organization Code is described 
in the module listing. 



Called by: IHEOPN 
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IHEOPP 

Calls: 

Supervisor (DCBD. GETMAIN,GETPOOL,OPEN) , 
IHEOPQ (Via XCTL), IHESAP, IHETSA 

Entry point: IHEOPPA 

Function: 

1. To invoke data management (OPEN 
macro) . 

2. To establish defaults at DCB exit. 

3. To acquire initial IOCBs for BSAM. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

AdHEOPN Parameter list) 

A ( Subparameter list) 
Subparameter list: 

XL^'U+n 1 (where n is the number of files 

to be opened) 

X* Access/Organization Code x • 

AL3(DCLCBj.) 

XL4* Merged attribute*. • 



X* Access/Organization Code n * 

AL3(DCLCBn) 

XL4» Merged attribute,^ 

NOTE: Access/Organization Code is described 
in the module listing. 

Called by: IHEOPO 

IHEOPQ 

Calls: 

Supervi sor (DCBD , FREEPOOL, GETMAI N , LOAD) , 
IHESAP, IHETSA 

Entry point: IHEOPQ A 

Function: 

1. To load record-oriented I/O 
interface modules. 

2. To link FCBs through the IHEQFOP 
chain . 

3. To acquire the initial IOCBs for 
BDAM and BIS AM linkage. 

4. To simulate PUT PAGE when opening a 
PRINT file. 

Linkage: 

RA: A (Parameter list) 



Parameter list: 

AdHEOPN parameter list) 
A (Subparameter list) 
A (Data management OPEN parameter 
list) 

Subparameter list: 

XL4*4*n' (where n is the number of 

files to be opened) 
X ' Access/Organization Code n * 
AL3(DCLCB L ) 
XL* * Merged attri butes* ' 



X ' Access/Organiz at ion Coden ' 

AL3(DCLCB n ) 

XL4' Merged attributes n * 

Data management OPEN parameter list: 
XL4*4*n ( (where n is the number of 

files to be opened) 
X (Flags for data management OPEN 

executor t ) 
AL3(DCBi) 



X( Flags for data management OPEN 

executor n ) 
AL3(DCBn) 

NOTE: Access/Organization Code is described 
in the module listing. 

Called by: IHEOPP 

IHEOPZ 

Calls: 

Supervisor (CHECK, CLOSE, DCB, DCBD, FREE- 
MAIN, FREEPOOL, GETBUF , GETMAIN, OPEN) 

Entry point: IHEOPZ A 

Function: 

To provide the format for the initial 
allocation of a volume assigned to a 
REGIONAL data set when opened for DIRECT 
OUTPUT. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(Merged attributes) 

A (Entry in IHEOPN Parameter list) 

A(DCLCB) 

Called by: IHEOPN 

IHEOSD 

Calls: TIME macro 

Entry point: IHEOSDA 
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Function: To obtain current date. 

Linkage: 

RA: A (Parameter list) 
Parameter list: A (Target SDV) 

Called by: Compiled code 

IHEQSE 

Calls: IHESAP, IHETSA (to terminate the 
task) 

Entry point: IHEOSEA 

Function: 

To terminate the current task abnormally, 
raising the FINISH condition if it is the 
major task. 

Called by: Compiled code 

I HEPS I 

Calls: STIMER macro 

Entry point: IHEOSIA 

Function: 

To use the STIMER macro with the WAIT 
option for the implementation of DELAY. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

Interval of delay, in milliseconds, in 

a fullword 

Called by: Compiled code 

IHEOSS 

Calls: IHESAP, IHETSA (to terminate the 
task) 

Entry point: IHEOSSA 

Function: 

To raise the FINISH condition and 
abnormally terminate the job step. 

Linkage: None 

Called by: Compiled code 

IHEOST 

Entry Point: IHEOSTA 

Function: 

To use the TIME macro to obtain the time 
of day. 



Linkage: 

RA: A (Parameter list) 
Parameter list: A (Target SDV) 

Called by: Compiled code 



IHEOSW 

Calls: 

Supervisor (FREEMAIN,WAIT) , IHEJXI, 
IHESAP, I/O transmit nodule whose address 
is in the FCB 

Entry point: IHEOSWA 

Function: 

ro determine whether a specified number 
of events has occurred. If not, to wait 
until the required number is complete, 
and, in the case of I/O events, to branch 
to the I/O transmit module (which raises 
I/O conditions if necessary) . 

This module is used in a non-multitasking 
environment. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

Word 1: 

1. If all events are to be waited 
on: 

Byte * X'FF' 
Bytes 1-3 not used 

2. If a specified number (N) of 
events is to be waited on: 

Byte * X'OO' 
Bytes 1 - 3 « A(N) 

Subsequent words (one for each element 
or array event) : 

1. Array event: 

Byte = dimensionality 
Bytes 1 - 3 s A(ADV) 

2. Element event: 
Byte = X'OO' 

Bytes 1 - 3 = A (Event variable) 

(High- order byte of last argument 
indicates end of parameter list. ) 

Called by: Compiled code 

IHEPDF 

Calls: IHEDMA. IHEJXI 

Entry point: IHEPDFO 
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Function: 



Function: 



PROD for an interleaved array of real 
fixed-point binary or decimal elements. 
Result is real short or long 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array) 

A (Target) 

A(DED for target) 

Called by: Compiled code 

IHEPDL 

Calls: IHEJXI 

Entry point: IHEPDLO 

Function: 

PROD for an interleaved array of real 
long floating-point elements. Result is 
real long floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

IHEPDS 

Calls: IHEJXI 

Entry point: IHEPDSO 

Function: 

PROD for an interleaved array of real 
short floating-point elements. Result is 
real short floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

IHEP > W 

Calls: IHEJXI 

Entry point: IHEPDWO 



PROD for an interleaved array of complex 
short floating-point elements. Result is 
complex short floating-point. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

IHEPDX 

Calls: IHEDMA, IHEJXI 

Entry point: IHEPDXO 

Function: 

PROD for an interleaved array of complex 
fixed-point binary or decimal elements. 
Result is complex short or long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array ) 

A(Target) 

A(DED for target) 

Called by: Compiled code 

IHEPD2 
Calls: IHEJXI 

Entry point: IHEPDZO 

Function: 

PROD for an interleaved array of complex 
long floating-point elements. Result is 
complex long floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 
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IHEPRT 



Function: 



Calls: 

Supervisor (WTO, EXTRACT) , IHEIOF, 
IHEOCL, IHESAP 



Entry point IHEPRTA 

Function: 

To COPY a data field on the SYSPRINT 
file, opening it if necessary. 

Linkage: 

RA: A (Character string) 
RB: A (Half word containing length of 
character string) 

Called by: IHEIOD,IHELDI 

Entry point IHEPRT B 

Function: 

To write an error message on the 
SYSPRINT file, opening it if necessary. 
Also, to prepare for system action for 
CHECK condition. 

Linkage: As for IHEPRTA 

Called by: IHEDDO, IHEERR, IHEESM, IHEESS 

IHEPSF 

Calls: IHEDMA, IHEJXS 

Entry point: IHEPSFO 

Function: 

PROD for a simple array of real 
fixed-point binary or decimal elements. 
Result is real short or long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

MADV) 

A (Number of dimensions) 

A(DED of the array) 

A (Target) 

A(DED for target) 

Called by: Compiled code 
IHEPSL 

Calls: IHEJXS 
Entry point: IHEPSLO 



PROD for a simple array of real long 
floating-point elements. Result is real 
long floating-point. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(rarget) 

Called by: Compiled code 

IHEPSS 

Calls: IHEJXS 

Entry point: IHEPSSO 

Function: 

PROD for a simple array of real short 
floating-point elements. Result is real 
short floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

h(ADV) 

A (Number of dimensions) 

A(Target) 

Called by: Compiled code 

IHEPS W 

Calls: IHEJXS 

Entry point: IHEPSWO 

Function: 

PROD for a simple array of complex short 
floating-point elements. Result is 
complex short floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

IHEPSX 

Calls: IHEDMA, IHEJXS 

Entry point: IHEPSXO 
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Functions 

PROD for a simple array of complex 
fixed-point binary or decimal elements. 
Result is complex short or long 
floating-point. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array elements) 

A (Target) 

A(DED for target) 

Called by: compiled code 

I HE PS Z 

Calls: IHEJXS 

Entry point: IHEPSZO 

Function: 

PROD for a simple array of complex long 
floating-point elements. Result is 
complex long floating-point. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

IHEPTT 

This module is used in a multitasking 
environment and is equivalent to module 
IHEPRT in a non-multitasking environment. 

Calls: 

Supervisor (DEQ, ENQ, EXTRACT, WTO), 
IHEIOF, IHEOCT, IHETSA 

Entry point IHEPTTA 

Function: 

To COPY a data field on the SYSPRINT 
file, opening it if necessary, in a 
multitasking environment. 

Linkage: 

RA: A (Character string) 
RB: A (Half word containing length of 
character string) 

Called by: IHEIOD, IHELDI, IHETEX 



Entry point IHEPTTB 

Function: 

To write, in a multitasking 
environment, an error message on the 
SYSPRINT file, opening it if necessary. 
Also, to prepare for system action for 
CHECK condition. 

Linkage: As for IHEPTTA 

Called by: IHEDDT, IHEERR, IHETSA 

IHERES 

Entry points IHEREST 

Function: 

to restart program at last checkpoint. 

Linkage: None 
Called by: compiled code 
Entry point: IHERESN 
Function: 

to cancel automatic restart. 
Linkage: none 
Called by: compiled code, IHESAP 

IHESAP 

Calls: 

Supervisor ( FREEMAIN, GETMAIN, SPIE) , 
IHEBE6, IHEMAN, IHEDDO, IHEOCL, IHEPRT 

Function: 

Storage management in a non-multitasking 
environment. 

Entry point IHESADA (Get PSA) : 

Function: 

To provide a DSA for a procedure or 
begin block and to set DR to point to 
it. 

Linkage: 

RO: Length of DSA 

DR: A( Current save area) 

Called by: Prologues 
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Entry point IHESADB (Get VDA) ; 

Function: 

To get a VDA for compiled code; sets 
RA=A(VDA). 

Linkage : 

RO: Length of VDA (excluding control 

words) 
DR: A (Current save area) 

Called by: Compiled code 

Entry point IHESADD (Get CONTROLLED 
variable) : 

Function: 

To provide storage for an allocation of 
a controlled variable, and to place the 
address of its fourth word in its 
pseudo-register . 

Linkage : 

RO: Length of area (not including 
control words) 

RA: A(Controlled-variable pseudo- 
register) 

Called by: Compiled code 

Entry point IHESADE (Get LWS ) : 

Function: 

To provide a new LWS, and to update the 
LWS pseudo-registers. 

Linkage : None 

Called by: Library modules 

Entry point IHESADF (Get Library VDA) : 

Function: 

To provide a VDA for library modules 
and to set RA = A (VDA) . 

Linkage : 

RO: Length of VDA (including control 
words) 

Called by: Library modules 

Entry point IHESAFA (END): 

Function: 

Frees the DSA current at entry together 
with its associated VDAs. Request to 
free the DSA of the main procedure 
results in raising FINISH, closing all 
opened files, releasing automatic 



storage to the supervisor and finally 
returning to the supervisor with a 
return code of zero. 

Linkage: None 

Called by: Epilogues 

Ent ry point IHESAFB (RETURN) : 

Function: 

Frees all chain elements up to and 
including the last procedure DSA in the 
chain. Can terminate a main procedure 
as in IHESAFA. 

Linkage: None 

Called by: Compiled code 

Entry p oint IFIES IF C (GO TO) : 

Function: 

The DSA indicated by the invocation 
count, or pointed to by DR, is made 
current. All chain elements up to this 
DSA, with the exception of its VDAs and 
itself, are freed. 

Linkage: 

RA: A (Eight-byte word-aligned parameter 

list) 
Parameter list: 

Word 1 = Eithe r Invocation count (bit 
of word 2=0) 
Or PR offset (bit of word 
2 = 1) 
Word 2 = A (Location to which control 
is to be returned) 

Called by: Compiled code 

Entry point IHESAFD (F ree VDA/LWS) 

Function: 

Frees the VDA or LWS at the end of the 
DSA chain. 

Linkage: 

IHEQSLA: A (VDA or LWS to be freed) 
(A VDA or LWS can be freed only when it 
is the last allocation) 

Called by: Compiled code, library modules 

Entry point IHES FF (Free controlled 
variable) : 

Function: 

Frees the latest allocation of a 
controlled variable, and updates the 
associated pseudo- register. 
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Linkage : 

RA: A (Controlled variable pseudo- 
register) 

Called by: Compiled code 



Entry point IHESAFO 

Function: 

To close all files and to return to the 
supervisor. 

Linkage : None 

Called by: 

Library modules, IHEDUMP, IHEOSE, 
IHEOSS 

Entry point IHESAPA 
Function: 

1. To provide a PRV and LWS for a main 
procedure, and to issue a SPIE 
macro; then to transfer control to 
an address constant named IHEMAIN. 

2. To pass a PARM parameter from the 
EXEC card. 

Linkage : 

L(PRV) from linkage editor 
L(LWS) from assembly of IHELIB 

Called by: Initial entry 

Entry Point IHESAPB 

Function: 

As for IHESAPA, except that the code 
handling PARM parameter is bypassed. 

Linkage : 

L(PRV) from linkage editor 
L(LWS) from assembly of IHELIB 

Entry point IHESAPC 

Function: 

As for IHESAPA, but also reserves a 
512-byte area for optimization 
purposes . 

Linkage : 

L(PRV) from linkage editor 
L(LWS) from assembly of IHELIB 



Entry point IHESAPD 

Function: 

As for IHESAPB, but also reserves a 
512-byte area for optimization 
purposes. 



Linkage: 

L(PRV) from linkage editor 
L(LWS) from assembly or IHELIB 



Entry point IHESARA 

Function : 

To restore the environment of a program 
to what it was before: 

1. the execution of an ON statement 
associated with the on-unit to be 
entered, or 



2. the passing of the entry parameter 
associated with the called 
procedure. 

Then to branch to the on-unit or the 
procedure. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 

A(Entry parameter). The entry 

parameter is an 8-byte field 

containing: 

1st word: On-unit or entry address 

2nd word: Invocation count of the 
DSA associated with 
either the passing 
procedure or the 
procedure in which the ON 
statement was executed 

Called by: Compiled code, IHFERR 

Entry point IHESARC 

Function: 

To place the return code in the 
pseudo-register IHEQRTC. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A (Return code) (The return code is 
fullword fixed binary.) 

Called by: Compiled code 
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Entry point IHESATA 

Function: 

To provide the interface between 0/S 
STAE routine and the PL/I STAE routine. 



Entry point IHESHSC 

Function: 

COSH(x), where x is real short 
floating-point. 



Linkage: 

RA = address of 0/S STAE parameter 
list- 
Called by: SUPERVISOR 

Calls: 

IHESHL 

Calls: IHEEXL 

Entry point IHESHLS 

Function: 

SINH(x), where x is real long floating- 
point. 

Linkage: 

RA: A Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 

Entry point IHESHLC 

Function: 

COSH(x), where x is real long 
floating- point . 

Linkage: As for IHESHLS 

Called by: Compiled code 
IHESHS 

Calls: IHEEXS 
Entry point IHESHSS 

Function: 

SINH(x), where x is real short 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code 



Linkage: As for IHESHSS 
Called by: Compiled code 

IHESIZ 

Entry point: IHESIZE 

Function: 

to return the length of the PRV in RA. 
Linkage: none 
Called by: IHESAP, IHETSAP 

IHESMF 

Calls: IHEDMA, IHEJXI 

Entry point: IHESMFO 



Function: 

SUM for an interleaved array of real 
fixed-point binary or decimal elements. 
Result is real short or long 
floating-point. 



Linkage : 

RA: A(Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array) 

A (Target) 

A(DED for target) 

Called by: Compiled code 



IHESMG 
Calls: IHEJXI 

Entry point IHESMGR 

Function : 

SUM for an interleaved array of real 
short floating-point elements. Result 
is real short floating-point. 
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Linkage : 



Linkage : 



RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

Entry point IHESMGC 

Function: 

SUM for an interleaved array of complex 
short floating-point elements. Result 
is complex short floating-point. 

Linkage: As for IHESMGR 

Called by: Compiled code 
IHESMH 

Calls: IHEJXI 
Entry point IHESMHR 

Function: 

SUM for an interleaved array of real 
long floating-point elements. Result 
is real long floating-point. 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

Entry point IHESMHC 

Function: 

SUM for an interleaved array of complex 
long floating-point elements. Result 
is complex long floating-point. 

Linkage: As for IHESMHR 

Called by: Compiled code 

IHESMX 

Calls: IHEDMA, IHEJXI 

Entry point: IHESMXO 

Function: 

SUM for an interleaved array of complex 
fixed-point binary or decimal elements. 
Result is complex short or long 
floating-point , 



RA: h (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array) 

A(Target) 

A(DED for target) 

Called by: Compiled code 



IHESNL 

Entry point IHESNLS 

Function: 

SIN(x), where x is real long 
floating-point. 



Linkage: 

RA: A(Parameter list) 
Parameter list: 

Mx) 

A (Target) 

Called by: Compiled code, IHEEXZ, IHESNZ 



Entry p oint IHESNL Z 

Function: 

SIND(x), where x is real long 
floating-point. 

Linkage: As for IHESNLS 
Called by: Compiled code 

Entry point IHESNLC 

Function: 

COS(x) f where x is real long 
floating-point . 

Linkage: As for IHESNLS 

Called by: Compiled code, IHEEXZ, IHESNZ 

Entry point IHESNLK 

Function: 

COSD(x), where x is real long 
floating-point. 

Linkage: As for IHESNLS 

Called by: Compiled code 
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IHESNS 

Entry point IHESNSS 

Function: 

SIN(x), where x is real short 
floating-point. 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code, IHEEXW, IHESNW 

Entry point IHESNSZ 

Function: 

SIND(x), where x is real short 
floating-point. 

Linkage: As for IHESNSS 
Called by: Compiled code 

Entry point IHESNSC 

Function: 

COS(x), where x is real short 
floating-point. 

Linkage: As for IHESNSS 

Called by: Compiled code, IHEEXW, IHESNW 

Entry point IHESNSK 

Function: 

COSD(x), where x is real short 
floating-point. 

Linkage: As for IHESNSS 

Called by: Compiled code 
IHESNW 

Calls: IHEEXS, IHESNS 
Entry point IHESNWS 

Function: 

SIN(z), where z is complex short 
floating-point. 



Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code 

Entry point IHESNWZ 

Function : 

SINH(z), where z is complex short 
floating-point. 

Linkage: As for IHESNWS 

Called by: Compiled code 

Entry point IHESNWC 

Function: 

COS(z), where z is complex short 
floating-point. 

Linkage: As for IHESNWS 

Called by: Compiled code 

Entry point IHESNWK 

Function: 

COSH(z), where z is complex short 
floating-point. 

Linkage: As for IHESNWS 

Called by: Compiled code 
IHESNZ 

Calls: IHEEXL, IHESNL 
Entry point IHESNZS 

Function: 

SIN(z), where z is complex long 
floating-point. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code 

Entry point IHESNZZ 

Function: 

SINH(z), where z is complex long 
floating-point. 
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Linkage: As for IHESNZS 
Called by: Compiled code 

Entry point IHESN2C 

Function: 

COS(z), where z is complex long 
floating-point. 

Linkage: As for IHESNZS 
Called by: Compiled code 



Linkage : 

RA: A(Parameter list) 
Parameter list: 

A(x) 

A(Target) 

Called by: Compiled code, IHEABW, IHESQW 

IHESQW 

Calls: IHESQS, IHEABW 

Entry point: IHESQWO 



Entry point IHESNZK 
Function: 

COSH(z), where z is complex long 
floating-point- 
Linkage: As for IHESNZS 
Called by: Compiled code 
IHESPR 

Entry point: IHESPRT 
Function: 

Contains the default DCLCB for SYSPRINT. 
This module is used only when no other 
DCLCB is provided. 

Called by: IHEPRT, IHEPTT 

IHESQL 

Entry point: IHESQLO 

Function: 

SQRT (x) , where x is real long 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code, IHEABZ, IHESQZ 

IHESQS 

Entry point: IHESQSO 

Function: 

SQRT(x), where x is real short 
floating-point . 



Function : 

SQRT(z), where z is complex short 
floating-point. 



Linkage : 

RA: A(Parameter list) 
Parameter list: 

A(z) 

A(Target) 

Called by: Compiled code 

IHESQZ 

Calls: IHEABZ, IHESQL 

Entry point: IHESQZO 

Function: 

SQRT(z), where z is complex long 
floating-point. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code 

IHESRC 

Entry point IHESRCA 

Function: 

Returns SDV of erroneous field 
(ONSOURCE pseudo-variable). If used 
out of context, the ERROR condition is 
raised. 

Linkage: 

RA: AC Parameter list) 
Parameter list: A (Dummy SDV) 
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Entry point IHESRCB 

Function: 

Assigns erroneous character to target 
(ONCHAR built-in function) . If used 
out of context, then 'blank* is 
returned. 



Linkage: 

RA: A (Parameter list) 
Parameter list: A(Target SDV) 



Entry point IHESRCC 

Function: 

Returns SDV of erroneous field 
(DATAFIELD). If used out of context, a 
null string is returned. 

Linkage: As for IHESRCA 

Entry point IHESRCD 

Function: 

Returns SDV of erroneous character. 
(ONCHAR pseudo-variable) . If used out 
of context, the ERROR condition is 
raised. 

Linkage: As for IHESRCA 

Entry point IHESRCE 

Function: 

Returns SDV of the name of the file 
(ONFILE) which caused entry to the 
current ON block. If used out of 
context a null string is returned. 

Linkage: As for IHESRCA 

Fntrv point IHESRCF 

Function : 

Returns SDV of erroneous field 
(ONSOURCE built-in function). If used 
out of context, a null string is 
returned. 

Linkage: As for IHESRCA 

IHESRD 

Entry point: IHESRDA 

Function: 

Returns SDV of current key (ONKEY 
built-in function) . If used out of 
context, a null string is returned. 



Linkage: 

RA: A (Parameter list) 
Parameter list: A (Dummy SDV) 



IHESRT 

Calls: 

IHESAP, IHETSA, Supervisor (GETMAIN, 
FREEMAIN, LINK, SPIE), SORT 

Function: 

To call dynamically, through the use of 
a LINK macro, the operating system 
Sort/Merge from within a PL/I 
procedure, and, optionally, permitting 
the use of Sort/Merge user exits E15 
and E35 to invoke PL/I exit procedures 
contained within the calling PL/I 
procedure. 

Entry point IHESRT A 

Function: 

To call operating system Sort/Merge to 
sort a predefined file (SORTIN) placing 
the sorted records on another 
predefined file (SORTOUT) . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

1. A(A character string which 
represents the Sort/Merge control 
card to describe the sort fields 
contained in the record. ) 

2. A(A character string which 
represents the Sort/Merge control 
card to describe the record 
format of the records which are 
to be sorted.) 

3. A(A full word fixed binary value 
specifying the amount of core 
storage available to Sort/Merge.) 

4. A(A full word fixed binary value 
to be used as a return code from 
the sort. A return code of 
indicates the successful 
completion of the sort, 16 
indicates an unsuccessful sort 
operation.) 

5. A (SDV for the DD name replacement 
string) . This is an optional 
parameter. 

Called by: Compiled code (PL/I source 
statement) 
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Entry point IHESRTB 

Function: 

To call operating system Sort/Merge to 
sort individual records, passed to 
Sort/Merge through user exit E15 by a 
PL/I exit procedure, onto a predefined 
file (SORTOUT). 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

1, 2, 3, and 4 are as for IHESRrA 

5. A (The PL/I functional procedure 
entry name invoked by Sort/Merge 
user exit E15. This exit 
procedure returns a character 
string representing a record 
which is to be included in the 
sort.) 

6. as for 5 in IHESRTA 

Called by: Compiled code (PL/I source 
statement) 



Entry point IHESRTC 

Function: 

To call operating system Sort/Merge to 
sort a predefined file (SORTIN), 
passing individual sorted records 
through Sort/Merge user exit E35 to a 
PL/I exit procedure. 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

1, 2, 3, and 4 are as for IHESRTA 

5. A (The PL/I procedure entry name 
invoked by Sort/Merge user exit 
E35. This exit procedure 
receives a sorted record from the 
sort. ) 

6. as for 5 in IHESRTA 

Called by: Compiled code (PL/I source 
statement) 

Entry point IHESRTD 

Function: 

To call operating system Sort/Merge to 
sort individual records passed to the 
sort by an exit procedure, through user 
exit E15, and to pass the sorted 
records, through user exit E35, to an 
exit procedure. 



Linkage: 

RA: A(Parameter list) 
Parameter list: 

1, 2, 3, and *» as for IHESRTA 

5. as for IHESRTB 

6. as for 5 IHESRTC 

7. as for 5 in IHESRTA 



Called by: Compiled code (PL/I source 
statement) 



IHESSF 

Calls: IHEDMA, IHEJXS 

Entry point: IHESSFO 

Function: 

SUM for a simple array of real 
fixed-point binary or decimal elements. 
Result is real short or long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array) 

A (Target) 

A(DED for target) 

Called by: Compiled code 

IHESSG 

Calls: IHEJXS 

Entry point IHESSGR 

Function : 

SUM for a simple array of real short 
floating-point elements. Result is 
real short floating-point. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

Entry point IHESSGC 

Function: 

SUM for a simple array of complex short 
floating-point elements. Result is 
complex short floating-point. 
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Linkage: As for IHESSGR 
Called by: Compiled code 

IHESSH 
Calls: IHEJXS 

Entry point IHESSHR 

Function: 

SUM for a simple array of real long 
floating- point elements. Result is 
real long floating-point. 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A (Target) 

Called by: Compiled code 

Entry point IHESSHC 

Function: 

SUM for a simple array of complex long 
floating-point elements. Result is 
complex long floating-point. 

Linkage: As for IHESSHR 

Called by: Compiled code 
IHESSX 

Calls: IHEDMA, IHEJXS 
Entry point: IHESSXO 
Function: 

SUM for a simple array of complex 
fixed-point binary or decimal elements. 
Result is complex short or long 
floating-point- 
Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV) 

A (Number of dimensions) 

A(DED of the array ) 

A (Target) 

A(DED for target) 

Called by: Compiled code 

IHESTA 

Entry point: IHESTAA 



Function: 

Write out error messages under ABEND 
conditions. 

Linkage: 

RA: A(PLIST) 
PLIST: MLatest save area) 

MO/S STAE parameter list) 
A (First free core block) 

Unused 
A(Adcon list) 
MSYSPRINT in PRV) 

Called by: IHESAP 



IHESTG 

Calls: IHEJXI, IHEBSK 

Entry point IHESTG A 

Function: 

Given a structure dope vector and its 
DVD, returns a full word containing the 
string length which would result from 
the concatenation of all the elements 
of the structure. 

Linkage: 

RA: A( Structure dope vector) 

RB: A (DVD) 

RC: A( One- word target field) 

Called by: Compiled code 

Entry point IHESTGB 

Function: 

Given a structure dope vector and its 
DVD, assigns the result of 
concatenating all the elements of the 
structure to a string target. 

Linkage: 

RA: A( Structure dope vector) 
RB: A (DVD) 
RC: A( Target) 

Called by: Compiled code 
IHESTP 

Calls: IHEBSK, IHEBSM, IHEJXI 
Entry point: IHESTPA 

Function: 

Assigns a bit or character string to 
the elements of a scalar, array or 
structure variable. 
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Linkage: 

RA: A (Dope Vector) 

RB: A (Dope Vector Descriptor) 

RC: A(SDV) 

Called by: Compiled code. 



IHESTR 

Calls: IHESAP, IHETSA 

Entry point IHESTRA 

Function: 

To compute the address of the first 
element of a structure and the total 
length of the structure, using a 
complete structure dope vector. The 
result in the two-word target field is; 

1st word: A (Start of structure), in 
bytes and bit offset 

2nd word: Length of structure, in 
bytes 

Linkage: 

RA: A (Structure dope vector) 

RB: A (DVD) 

RC: A (Two-word target) 

Called by: Compiled code 

Entry point IHESTRB 

Function: 

Given a partially completed structure 
dope vector, to map a structure 
completely, namely: 

1. Locating each structure base 
element on the alignment boundary 
required by its data type. 

2. Calculating the offset of the start 
of each base element from the byte 
address of the beginning of the 
structure. 

3. Calculating the multipliers of all 
arrays appearing in the structure 
and calculating the offset of the 
virtual origin of each array from 
the byte address of the beginning 
of the structure. 

4. Calculating the total length of the 
structure. 

5. Calculating the offset from the 
maximum alignment boundary in the 
structure to the byte address of 
the start of the structure. 



The result is a completed structure 
dope vector, and a target field which 
contains: 
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31 



< 






Offset: Offset in bytes from the maximum 

alignment boundary in the structure 
to the start of the structure 

Length: Length of structure, in bytes 

Linkage: As for IHESTRA 

Called by: Compiled code 
Entry point IHESTRC 

Function: 

As for IHESTRB, but using the COBOL 
structure mapping algorithm. 

Linkage: As for IHESTRA 

Called by: Compiled code 
IHESUB 

Calls: IHETSAM 
Entry point: IHESUBA 

Function: 

to be attached by IHETSAP and pass 
control to IHETSAM. 

Linkage: 

R0( length of PRV) 
RA: A( Parameter list) 

Parameter list: 
A (IHETSAM) 
A (Parameter list) 

Called by (attached by): IHETSAP 

IHETAB 

Base address of table: IHETABS 

Function: 

This module is a table of default 
information provided for use at 
installation or when individual program 
replacements are required. It contains: 

1. Default PAGESIZE, LINESIZE, and left 
and right margin positions for all 
PRINT files. 
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2. Default tabulation positions for 
list- and data-directed PRINT file 
output . 

IHETCV 

Calls: Supervisor (FREEMAIN, GETMAIN) 

Entry point IHETCVA 

Function: 

To provide storage for an allocation of 
a controlled variable in a multitasking 
environment, and to place the address 
of its fourth word in its 
pseudo-register. 

Linkage: 

RO: Length of area (excluding control 

words) 
RA: A(Controlled-variable 

pseudo-register) 

Called by: Compiled code 

Entry point IHETCVB 

Function : 

Frees the latest allocation of a 
controlled variable in the current 
task, and updates the associated 
pseudo-register . 

Linkage : 

RA: ACControlled-variable 
pseudo-register) 

Called by: Compiled code 

IHETEA 

Calls: Supervisor (POST, WAIT) 

Entry point: IHETEAA 

Function: Event variable assignment. 

Linkage: 

RA: A (Source event variable) 
R3: A (Target event variable) 

Called by: Compiled code 

IHETER 

Entry point: IHETERA 

Function: 

To search for a matching ON field in a 
multitasking environment by chaining 
through DSAs and PRV VDAs. A return code 
is set in register BR to indicate the 
result of the search. 



Linkage: DR: A(LWE) 



Called by: IHEERR 



IHETEV 



Calls: Supervisor (POST, WAIT) 



Entry point: IHETEVA 



Function: 

COMPLETION pseudo-variable (COMPLETION(v) 
= expression) : sets the specified event 
variable complete or incomplete according 
to the evaluation of the expression. 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(Event variable) 

A(Fullword to hold completion value (in 

bit 24)) 

Called by: Compiled code 

IHETEX 

Calls: 

IHEERT, IHEPTT Supervisor (WTO, LOAD, 
DELETE, EXTRACT, ENQ, DEQ, PUT) 

Entry p oint IKETEXA 

Function: 

To generate a message when a task has 
been terminated whiie still active due 
to the freeing of the block in which 
the task was attached. 

Linkage: 

RA contains the address of a VDA which 
contains space for the creation of the 
message and the following parameters: 

A(IHEPTTB) 

A( Symbol table entry for which the 

task has been terminated) 
A(IHEQSPR) 

Called by: IHETSA 

Entry p oint IHETEXB 

Function: 

To generate a message when a task has 
been abnormally terminated by the 
operating system. 
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Linkage: 



Linkage : 



DR points to an area of storage 
containg a save area, an area for the 
creation of the message and the 
following parameters : 



Completion code 

A (Symbol table entry for the task 

which has been terminated) 
A(IHEQSPR) 



Called by: IHETSA 

Entry point IHETEXC 

Function: 

Version 5 entry point (instead of 
IHETEXB) 

Linkage: 

A(PROC NAME) 
Statement no. when task abended 
Offset when task abended 

A (Symbol table) 
Completion code 

A(SYSPRINT in major PRV) 

Called by: IHETSA 



IHETHL 

Calls: IHEEXL 

Entry point: IHETHLO 

Function: 

TANH (x) , where x is real long floating- 
point. 

Linkage: 

RA: A(Parameter list) 
Parameter list: 

A(x) 

A (Target) 

Called by: Compiled code, IHETNZ 

IHETHS 

Calls: IHEEXS 

Entry point: IHETHSO 

Function: 

TANH(x), where x is real short 
floating-point . 



RA: A (Parameter list) 
Parameter list: 

A(x) 

A(Target) 

Called by: Compiled code, IHETNW 



IHETNL 

Entry point IHETNLR 

Function: 

TAN(x), where x is real long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A( Target) 

Called by: Compiled code, IHETNZ 

Entry point IHETNLD 

Function: 

TAND(x), where x is real long 
floating-point. 

Linkage: As for IHETNLR 

Called by: Compiled code 

IHETNS 

Entry point IHETNSR 

Function: 

TAN(x), where x is real short 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(x) 

A(Target) 

Called by: Compiled code, IHETNW 

Entry point IHETNSD 

Function : 

TAND(x), where x is real short 
floating-point. 

Linkage: As for IHETNSR 

Called by: Compiled code 
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IHETNW 

Calls: IHETHS, IHETNS 

Entry point IHETNWN 

Function : 

TAN(z), where z is complex short 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code 

Entry point IHETNWH 

Function : 

TANH(z), where z is complex short 
floating-point. 

Linkage: As for IHETNWN 

Called by: Compiled code 
IHETNZ 

Calls: IHETHL, IHETNL 
Entry point IHETNZN 

Function: 

TAN(z), where z is complex long 
floating-point . 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(z) 

A (Target) 

Called by: Compiled code 

Entry point IHETNZ H 

Function : 

TANH(z), where z is complex long 
floating-point. 

Linkage: As for IHETNZN 

Called by: Compiled code 

IHETOM 

Calls: Supervisor (WTO, EXTRACT) 



Entry point IHETOMA 

Function : 

Issues WTO macro instruction if the 
program does not have a main procedure. 

Linkage: 

DR points to an area of storage which 
is used as a save area and as workspace 
to build up the message. 

Called by: IHEBEG 

Entry point IHETOMB 

Function: 

Issues WTO macro instruction if the PRV 
is longer than 4096 bytes. 

Linkage: 

As for IHETOMA 

Called by: IHEBEG 

Entry point IHETOMC 

Function: 

Issues WTO macro instruction if there 
has been an interrupt in the error 
handler. 

Linkage: 

As for IHETOMA 

Called by: IHEERR 

Entry point IHETOMD 

Function: 

Issues WTO macro instruction if the 
major task of a multitasking program 
has been terminated with an ABEND. The 
message contains the completion code. 

Linkage: 

As for IHETOMA but in addition the 
completion code is passed in the area 
pointed to by DR. 

Called by: IHETSA 

Entry point IHETOME 

Function : 

Issues WTO macro instruction if there 
is an abnormal KEY .condition when- 
CLOSING a file after a LOCATE 
statement. The file may be INDEXED 
(with RKP * 0) or REGIONAL. 
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Linkage: as for IHETOMA 
Called by: IHEOCL, IHEOCT 

IHETPB 

Entry point: IHETPBA 

Function: 



PRIORITY built-in function: returns the 
priority of a named task relative to the 
priority of the current task. 



Linkage: 



RA: A (Parameter list) 
Parameter list: 

A (Task variable) 

A(Fullword target field) 

Called by: Compiled code 



IHETPR 

Calls: Supervisor (CHAP, POST, WAIT) 

Entry point: IHETPRA 

Function: 

PRIORITY pseudo-variable (PRIORITY (v) = 
expression) : sets the priority of the 
specified task to the given value 
relative to the priority of the current 
task. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(Task variable), or zero (if current 

task) 

A (Relative priority) 

Called by: compiled code 



IHETSA 

Calls: 

Supervisor (ATTACH, DEQ, DETACH, EXTRACT, 
FREEMAIN, GETMAIN, LINK, POST, SPIE, 
STAE, WAIT), IHEBEG IHEDDT, IHEERR, 
IHEMAI, IHEITA, IHEOCT, IHEPTT, IHESIZ, 
IHETAB, IHETEX 

Function: 

Object program management in a 
multitasking environment. 



Entry point IHETSAA 
Function: 

1. Obtains storage for the PRV VDA, 
task variable, and event variable 
for the major task, ECBLIST, CTECB 
and TCA. 

2. Attaches the PL/I major task and 
then enters a wait state until 
either the event variable for the 
major task or the CTECB is 
completed. 

The execution of IHETSAA is termed the 
control task . Return is made to the 
calling program when there are no 
outstanding tasks in the calling 
program. 

Linkage: 

L(PRV) from IHESIZE 

L(LWS) from assembly of IHELIB 

Called by: 

Program that calls the PL/ I program. 

Entry point IHETSAC 

Function : 

To place the return code in the 
pseudo- register IHEQRTC. 

Linkage: 

RA: A(Parameter list) 
Parameter List: 

A (Return code) (The return code is 

fullword fixed binary.) 

Called by: Compiled code 

Entry p oint IHETSAD (Get PSA) 

Function: 

To provide a DSA for a procedure or 
begin block and to set DR to point to 
it. 

Linkage: 

RO: Length of DSA 

DR: A (Current save area) 

Called by: Prologues, IHESRT 

Entry point IHETSAE (END) 

Function: 

Frees the DSA current at entry and its 
associated VDAs, and abnormally 
terminates any tasks attached in the 
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block. A request to free the first DSA 
in a subtask results in the closing of 
all files opened, the dequeuing of 
resources enqueued, and the release of 
all dynamic storage allocated in that 
task. A request to free the DSA of the 
main procedure also raises the FINISH 
condition, but does not cause 
controlled storage allocated in the 
major task to be freed. 



Linkage: None 



Linkage: None 

Called by: Library modules 

Entry point IHETSAM 

Function: 

Initializes new subtasks, and, where 
applicable, the PRV and primary LWS for 
the major task. Issues a SPIE and STAE 
macro instructions and branches to the 
main procedure. 



Called by: Epilogues, IHESRT 



Linkage: 



Ent ry point IHETSAF (Free VDA/LWS) 

Function: 

Frees the VDA or LWS at the end of the 
DSA chain. 

Linkage: 

IHEQSLA: A(VDA or LWS to be freed) 
Only the most recently allocated VDA or 
LWS can be freed. 

Called by: Compiled code, library modules 

Entry point IHETSAG (GO TO) 

Function: 

The DSA indicated by the invocation 
count, or pointed to by DR, is made 
current. All chain elements up to this 
DSA, with the exception of its VDAs and 
itself, are freed. Any active tasks 
attached to the DSAs freed are 
abnormally terminated. 

Linkage: 

RA: A (Eight- byte word-aligned parameter 
list) 

Parameter list: 

Word 1 =either Invocation count (bit 
of word 2=0) 
or PR offset (bit of word 
2=1) 

Word 2=A( Location to which control is 
to be returned) 

Called by: Compiled code 

Entry point IHETSAL (Get LWS) 

Function: 

To provide a new LWS, and to update the 
LWS pseudo-registers. 



RA: A( Parameter list) 
Parameter list contains control 
information from the control task. 



Called by: IHESUBA 

Entry point IHETSAN 

Function: 

To change the environment of a program 
to that which existed at the time of 

1 . the execution of an ON statement 
associated with the on-unit to be 
entered, or 

2. the passing of the entry parameter 
associated with the called 
procedure. 

Then to branch to the on-unit or the 
procedure. 

Linkage: 

RA: A( Parameter list) 

Parameter list: 

A(Entry parameter). The entry 
parameter is an 8-byte field 
containing: 

1st word: On-unit or entry address 

2nd word: Invocation count of the DSA 
associated with either the 
passing procedure or the 
procedure in which the ON 
statement was executed 

Called by: Compiled code, IHEERR 

Entry point IHETSAP 

Function: 

As IHETSAA, but also passes a PARM 
parameter from the the EXEC card. 



Chapter 9: Module Summaries 145 



Linkage: 

L(PRV) from IHESIZE 

L(LWS) from assembly of IHELIB 

Called by: Initial entry 



Entry p oint IHETSAW (Get Library VDA) 

Funct ion : 

To provide a VDA for library modules 
and to set RA = A (VDA) 



Entry point IHETSAR (RETURN) 

Function: 

Frees all chain elements up to and 
including the last procedure DSA in the 
chain. Terminates the main procedure 
and subtasks as in IHETSAE. 

Linkage : None 

Called by: Epilogues 

Entry point IHETSAT 

Function: 

To implement a CALL statement with a 
task option: 

1. Completes the parameter list 
(reserved fields) 

2. Requests control task to attach 
subtask. 

Linkage : 

RA: A (Parameter list) 

Parameter list: 

A (Task variable) (Byte = X'80' if 

no PRIORITY option; bytes 1-3=0 

if no TASK option) 

A (Event variable) (Zero if no EVENT 

option) 

Relative priority 

A (Called procedure) 

Reserved 

Reserved (X'80* if no argument list) 

Variable length argument list for 

called procedure (Omitted if no 

argument list: X'SO* in first byte of 

last word indicates end of list.) 

Called by: Compiled code 

Entry point IHETSAV (Get VDA) 

Function: 

To get a VDA for compiled code; sets 
RA=A(VDA) . 

Linkage : 

RO: Length of VDA (excluding control 

words) 
DR: A (Current save area) 

Called by: Compiled code 



Linkage: 



RO: Length of VDA (including control 
words) 



Called by: Library modules 
Ent r y point IH E TSAX 

Function: 

Function: 

STAE exit routine. Enqueues on control 
task if necessary. Requests detach of 
an/ subtasks, informs control task that 
task has abnormally terminated. 

Linkage: None 

Called by: Supervisor 

Ent ry po int IH E TSAY 

Function: 

Completes the implementation of STOP: 
closes all opened files, releases 
dynamic storage, and requests that all 
subtasks of the control task, including 
itself, be detached. 

Linkage: 

RA: Return code 

Called by: IHEDUM, IHETSS 

Entry point IHETSAZ 

Function: 

Abnormal end of task: closes all files 
opened in task, releases dynamic 
storage, and terminates the task and 
all subtasks attached by it. 

Linkage: 

RA: Return code 

Called by: IHEDUM, IHEERR, IHETSE 
IHETSE 

Calls: IHEERR, IHETSA 
Entry point: IHETSEA 
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Function : 



1. Array event: 



To abnormally terminate the current task, 
and to raise the FINISH condition if the 
current task is the major task. 

Linkage: None 

Called by: Compiled code 

IHETSS 

Calls: IHEERR, IHETSA 

Entry point: IHETSSA 

Function: 

To raise the FINISH condition and 
abnormally terminate the PL/I program in 
a multitasking environment. 

Linkage: None 

Called by: Compiled code 

IHETSW 

Calls: IHEERR, IHEJXI 

Supervisor (FREEMAIN, POST, WAIT) , IHEJXI, 
IHETSA, the I/O transmission module whose 
address is in the FCB. 

Entry point IHETSWA 

Function: 

To determine whether a specified number 
of events has occurred. If not, to 
wait until the required number is 
complete, and, in the case of I/O 
events, to branch to the I/O 
transmission module (which raises I/O 
conditions if necessary). This module 
is used in a multitasking environment. 

Linkage : 

RA: A (parameter list) 
Parameter list: 

Word 1: 

1. If all events are to be waited 
on: 

Byte = X'FF' 
Bytes 1-3 not used 

2. If a specified number (N) of 
events is to be waited on: 

Byte = X^O' 
Bytes 1-3 = A(N) 

Subsequent words (one for each 
element or array event) : 



Byte = dimensionality 
Bytes 1-3 = A(ADV) 

2. Element event: 

Byte = X^O* 

Bytes 1-3 = A (EVENT variable) 



(The high-order byte of the last 
argument indicates the end of the 
parameter list.) 



Called by: Compiled code 
IHEUPA 
Ent ry Point IHEUPAA 

Function: 

To zero the real part of a complex 
coded data item and to return the 
address of the imaginary part. 

Linkage: 

RA: A (Source) 
RB: A (Source DED) 
WRCD: Admaginary part) 

Called by: IHEDCN, IHEDBN 

Ent ry P oin t IH EUPAB : 

Function: 

To return the address of the imaginary 
part of a complex coded data item if 
switch is on, and to zero the imaginary 
part if switch is off. 

Linkage: 

RA: A( Source) 

RB: A (Source DED) 

WSWA: Switch for update address only 

WRCD: Admaginary part) 

Called by: 

IHEDBN, IHEDCN, IHEDIA, IHELDI , IHEDID, 
IHEDIE, IHEDNC, IHEDOM, IHEVCS 

IHEUPB 

Calls: IHEDMA 

Entry Point IHEUPBA : 

Function: 

To zero the real part of a complex 
numeric field and to return the address 
of the imaginary part. 
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Linkage: 

RA: A (Source) 
RB: A (Source DED) 
WRCD: A (Imaginary part) 

Called by: IHEDCN, IHEDBN 



Entry Point IHEUPBB : 

Function: 

To return the address of the imaginary 
part of a complex numeric field if 
switch is on, and to zero the imaginary 
part if switch is off. 

Linkage: 

RA: A (Source) 

RB: A (Source DED) 

WSWA: Switch for update address only 

WRCD: A (Imaginary part) 

Called by: 

IHEDBN, IHEDCN, IHEDIA, IHEDID, IHEDIE, 
IHEDOM, IHEVCS 

IHEVCA 

Entry Point: IHEVCAA 

Function: 

To define the attributes of arithmetic 
data in character form by producing a DED 
(flags, p, g) . 

Linkage: 

RA: A (Target DED) 

WNCP: A (Start and end addresses of data 
to be analysed) 

Called by: 

IHEDIA, IHEDIM, IHEDOM, IHELDI 
IHEVCS 
Calls: 

IHEDMA, IHEDNB, IHEDNC, IHEUPA 
Entry point IHEVCSA 

Function: 

To direct the conversion of character 
representation of complex data to 
internal string data. The character 
data is first converted to coded 
complex, with attributes derived from 
the real and imaginary parts of the 
source data (according to the 



arithmetic conversion package rules) 
and then converted to string. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A( Start and end addresses of real 

data) 
A (Real DED) 
A (Start and end addresses of 

imaginary data) 
A (Imaginary DED) 
A (Target SDV) 
A (Target DED) 
A (Real FED) 
A (Imaginary FED). 

Called by: IHEDIM, IHEDOM, IHELDI 

Entry point IHEVCSB 

Function: 

As for IHEVCSA but the conversion is to 
coded complex only. 

Linkage: As for IHEVCSA 

Called by: As for IHEVCSA 

IHEVFA 

Calls: IHEVTB 

Entry point: IHEVFAA 

Function: 

R adix conversion : binary to decimal 

To convert long floating-point to packed 

decimal intermediate. 

Linkage : 

WINT: Long precision floating-point 
number 

Called by: IHEDMA 

IHEVFB 

Entry point: IHEVFBA 

Function: 

To convert a long precision 
floating-point number to a fixed-point 
binary number with specified precision 
and scale 
factor. 

Linkage : 

WINT: Long precision floating-point 

number 
WRCD: A( Target) 

A (Target DED) 



148 



Called by: IHEDMA 

IHEVFC 

Entry point: IHEVFCA 



Function: 

To convert a long floating-point number 
to a floating-point variable with 
specified precision. 



Linkage: 

WINT: Long- precis ion floating-point 

number 
WRCD: A (Target) 

A (Target DED) 



Called by: IHEDMA 
IHEVFD 

Entry point: IHEVFDA 

Function: 

To convert a fixed-point binary integer 
with scale factor to long precision 
floating-point . 

Linkage: 

RA: A(Source) 
RB: A(Source DED) 

Called by: IHEDMA 

IHEVFE 

Entry point: IHEVFEA 

Function: 

To convert a floating-point number of 
specified precision to long precision 
f loating-point . 

Linkage: 

RA: A (Source) 
RB: A (Source DED) 

Called by: IHEDMA 

IHEVKB 



Entry point: IHEVKBA 



Function : 

To convert a fixed- or floating-point 
decimal numeric field to packed decimal 
intermediate. 

Linkage : 

RA: A (Source) 
RB: A (Source DED) 

Called by: IHEDMA 

IHEVKC 



Entry point: IHEVKCA 

Function: 

To convert a sterling numeric field to 
packed decimal intermediate. 

Linkage : 

RA: A (Source) 
RB: A (Source DED) 

Called by: IHEDMA 

IHEVKF 

Entry point: IHEVKFA 

Function: 

To convert packed decimal intermediate to 
a decimal fixed- or floating-point 
numeric field with specified precision. 

Linkage: 

WINT: Decimal integer 
WSCF: Scale factor 
WRCD: A( Target) 

A( Target DED) 

Called by: IHEDMA 

IHEVKG 

Entry point: IHEVKGA 

Function: 

To convert packed decimal intermediate to 
a sterling numeric field with specified 
precision. 

Linkage : 

WINT: Decimal integer 
WSCF: Scale factor 
WRCD: A( Target) 

A (Target DED) 

Called by: IHEDMA 
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IHEVPA 
Calls: IHEVTB 

Entry point: IHEVPAA 



Linkage : 

WINT: Decimal integer 
WSCF: Scale factor 
WRCD: A( Target) 

A( Target DED) 



Function: 

Radix conversion : decimal to binary 

To convert packed decimal intermediate to 

long precision floating-point. 



Linkage: 

WINT: Decimal integer 
WSCF: Scale factor 

Called by: IHEDMA 



IHEVPB 

Entry Point: IHEVPBA 

Function: 

To convert packed decimal intermediate to 
an F format item. 

Linkage: 

WINT: Decimal integer 

WSCF: Scale factor 

WFDT: A (FED) 

WRCD: A (Target) 

Called by: IHEDMA 

IHEVPC 

Entry point: IHEVPCA 

Function: 

To convert packed decimal intermediate to 
an E format item. 

Linkage: 

WINT: Decimal integer 

WSCF: Scale factor 

WFDT: A (FED) 

WRCD: A (Target) 

Called by: IHEDMA 

IHEVPD 

Entry point: IHEVPDA 

Function: 

To convert packed decimal intermediate to 
a decimal integer with specified 
precision and scale factor. 



Called by: IHEDMA 

IHEVPE 

Entry point: IHEVPEA 

Function: 

To convert an F/E format item to packed 
decimal intermediate. 



Linkage : 

RA: A( Source) 
RB: A (Source DED) 
WFED: A(FED) 

Called by: IHEDMA 



IHEVPF 

Entry point: IHEVPFA 

Function: 

To convert a decimal integer with 
specified precision and scale factor to 
packed decimal intermediate. 

Linkage : 

RA: A (Source) 
RB: A (Source DED) 

Called by: IHEDMA 

IHEVPG 

Entry point: IHEVPGA 

Function: 

To convert a binary fixed- or floating- 
point constant to long precision 
floating-point. 

Linkage : 

WCNP: A (Beginning of constant) 
A (End of constant) 

Called by: IHEDMA 

IHEVPH 

Entry point: IHEVPHA 
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Function: 



Linkage : 



To convert a bit strinq constant with up 
to 31 significant bits to long precision 
floating-point . 

Linkage: 

WCN1: A (Beginning of constant) 
A (End of constant) 

Called by: IHEDMA 

IHEVOA 

Entry point: IHEVQAA 

Function: 

To convert a floating point number of 
specified precision to a fixed-point 
binary number with specified precision 
and scale factor. 

Linkage: 

RA: A(Source) 

RB: A (Source DED) 

RC: A (Target) 

RD: A (Target DED) 

Called by: Compiled code, IHEVQB 

IHEVQB 

Calls: IHEVQA, IHEVTB 

Entry point: IHEVQBA 

Function: 

To convert a decimal constant to a coded 
arithmetic data type. 

Linkage: 

RA: A (First character of constant) 

RB: A (Last character of constant) 

RC: A (Target) 

RD: A (Target DED) 

WFED: A (FED) if constant is part of F or 

E format input 
WSWB: Switches specifying type of source 

string 

Called by: IHEDCN, IHEDIA 

IHEVQC 

Calls: IHEVSC, IflEVSE 

Entry point: IHEVQCA 

Function : 

To convert some coded arithmetic data 
types to F or E format or character 
string. 



RA: A (Source) 
RB: A (Source DED) 
RC: A (Target SDV) 
RD: A (Target DED) 
WFDT: A (FED) 

WSWB: Switches specifying type of target 
string 

Called by: IHEDNC, IHEDOA 

IHEVSA 

Entry point: IHEVSAA 

Function : 

To assign a fixed-length or VARYING bit 
string to a fixed-length or VARYING bit 
string. 

Linkage : 

RA: A (Source SDV) 

RB: A (Source DED) 

RC: A (Target SDV) 

RD: A (Target DED) 

Called by: Compiled code, IHEDIA, IHEDNB 

IHEVSB 

Entry point: IHEVSBA 

Function : 

To convert a fixed-length or VARYING bit 
string to a fixed-length or VARYING 
character string. 

Linkage : 

RA: A (Source SDV) 

RB: A (Source DED) 

RC: A (Target SDV) 

RD: A (Target DED) 

Called by: 

Compiled code, IHEDOB, IHEDOD, IHEDOE, 
IHELDO 

IHEVSC 

Entry point: IHEVSCA 

Function: 

To assign a fixed-length or VARYING, 
character string to a fixed- length or 
VARYING character string. 
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Linkage: 



Called by: 



RA: A (Source SDV) 

RB: A (Source DED) 

RC: A (Target SDV) 

RD: A (Target DED) 

Called by: 

Compiled code, IHEDIA, IHEDIB, IHEDID, 
IHEDIE, IHEDNC, IHEDOB, IHEDOD, IHELDI, 
IHEVQC 

IHEVSD 

Entry point IHEVSDA 

Function: 

To convert a fixed-length or VARYING 
character string to a fixed-length or 
VARYING bit string. The ONSOORCE 
address is stored. 

Linkage: 

RA: A (Source SDV) 
RB: A (Source DED) 
RC: A (Target SDV) 
RD: A (Target DED) 
WODF: A(Source SDV) 

Called by: 

Compiled code, IHEDIB, IHEDID, IHEDIE, 
IHELDI 

Entry point IHEVSDB 

Function: 

As for IHEVSDA, but the ONSOURCE 
address is not stored. 

Linkage: 

AS for IHEVSDA, but without WODF 

Called by: As for IHEVSDA 
IHEVSE 
Entry point IHEVSEA 

Function: 

To assign a fixed- length or VARYING 
character string to a pictured 
character string. The ONSOURCE address 
is stored. 

Linkage : 

RA: A (Source SDV) 
RB: A (Source DED) 
RC: A (Target SDV) 
RD: A (Target DED) 
WODF: A (Source SDV) 



Compiled code, IHEDIB, IHEDID, IHEDIE, 
IHEDOB 

Entry point IHEVSEB 

Function : 

AS for IHEVSEA, but the ONSOURCE 
address is not stored. 

Linkage: 

As for IHEVSEA, but without WODF 

Called by: IHEDNC, IHEVQC 

IHEVSF 

Entry Point: IHEVSFA 

Function: 

To convert a fixed-length or VARYING bit 
string to a pictured character string. 

Linkage : 

RA: A (Source SDV) 
RB: A (Source DED) 
RC: A (Target SDV) 
RD: A (Target DED) 

Called by: Compiled code, IHEDOB 

IHEVTB 

Base address of table: IHEVTBA 

Function : 

This module is a table of long precision 
floating-point numbers representing 
powers of 10 from 1 to 70. It is used by 
the radix conversion routines IHEVPA, 
IHEVQB, and IHEVFA. 

Linkage : 

Not called. Referenced as external data 
by IHEVPA, IHEVQB and IHEVFA. 

IHEXIB 

Entry point: IHEXIBO 

Function: 

x**n, where x is real fixed-point binary 
and n is a positive integer. 

Linkage : 

RA: A(x) 
♦RB: A (DED for x) 

RC: ACn) 

RD: A (Target) 
♦RE: A (Target DED) 
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Called by: Compiled code 

IHEXID 

Entry point: IHEXIDO 



Function: 

x**n, where x is real fixed- point 
decimal, and n is a positive integer. 



Linkage: 

RA: A(x) 

RB: A (DED for x) 

RC: A(n) 

RD: A (Target) 

RE: A (Target DED) 

Called by: Compiled code 



IHEXIL 

Entry point: IHEXILO 

Function: 

x**n, where x is real long 
floating-point, and n is an integer. 

Linkage: 

RA: A(x) 
RB: A(n) 
RC: A (Target) 

Called by: Compiled code 

IHEXIS 

Entry point: IHEXISO 

Function: 

x**n, where x is real short 
floating-point, and n is an integer. 

Linkage: 

RA: A(x) 
RB: A(n) 
RC: A (Target) 

Called by: Compiled code 

IHEXIU 

Calls: IHEMZU 

Entry point: IHEXIUO 

Function: 

z**n, where z is complex fixed binary and 
n is a positive integer. 



Linkage : 

RA: A(z) 

♦RB: A(DED for z) 

RC: A(n) 

RD: A (Target) 

*RE: A (Target) 

Called by: Compiled code 

IHEXIV 

Calls: IHEMZV 

Entry point: IHEXIVO 

Function: 

z**n, where z is complex fixed- point 
decimal and n is a positive integer. 

Linkage : 

RA: A(z) 

RB: A(DED for z) 
RC: A(n) 
RD: A (Target) 
*RE: A (Target DED) 

Called by: Compiled code 

IHEXIW 

Calls: IHEMZW 

Entry point: IHEXIWO 

Function: 

z**n, where z is complex short 
floating-point, and n is an integer. 

Linkage : 

RA: A(z) 
RB: A(n) 
RC: A(Target) 

Called by: Compiled code 

IHEXIZ 

Calls: IHEMZZ 

Entry point: IHEXIZO 

Function: 

z**n, where z is complex long 
floating-point, and n is an integer. 

Linkage : 

RA: A(z) 
RB: A(n) 
RC: A (Target) 

Called by: Compiled code 
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IHEXXL 



Linkage : 



Calls: IHEEXL, IHELNL 

Entry point: IHEXXLO 

Function: 

x**y, where x and y are real long 
floating-point . 

Linkage: 

RA: A(y) 
KB: A(x) 
RC: A (Target) 

Called by: Compiled code 

IHEXXS 

Calls: IHEEXS, IHELNS 

Entry point: IHEXXSO 

Function: 

x**y, where x and y are real short 
floating-point. 

Linkage: 

RA: A(y) 
RB: A(x) 
RC: A (Target) 

Called by: compiled code 

IHEXXW 

Calls: IHEEXW, IHELNS, IHELNW 

Entry point: IHEXXWO 

Function: 

z 1 **z 2 , where zi and z a are complex short 
floating-point. 

Linkage: 

RA: A(z a ) 
RB: A(z 1 ) 
RC: A (Target) 

Called by: Compiled code 

IHEXXZ 

Calls: IHEEXZ, IHELNL, IHELNZ 

Entry point: IHEXXZO 

Function: 

z,**z a , where z„ and z a are complex long 
floating-point . 



RA: A(z a ) 
RB: A(z,) 
RC: A(Target) 

Called by: Compiled code 



IHEYGF 

Calls: IHEDMA 

Entry point IHEYGFV 

Function : 

POLY (A,X) for both A and X vectors of 
real fixed-point binary or decimal 
numbers. Result is real short or long 
floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A(DED of argument 1) 

A(ADV of argument 2) 

A(DED of argument 2) 

A (Target) 

A(DED of target) 

Called by: Compiled code 



Entry point IHEYGFS 
Function: 

As for IHEYGFV but X is scalar. 

Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A(DED of argument 1) 

A (Argument 2) 

A(DED of argument 2) 

A (Target) 

A(DED of target) 

Called by: Compiled code 

IHEYGL 

Entry point IHEYGLV 

Function: 

POLY (A,X) for both A and X vectors of 
real long floating-point numbers. 
Result is real long floating-point. 



15U 



Linkage: 



IHEYGW 



RA: A (Parameter list) 

Parameter list: 

A(ADV of argument 1) 
A(ADV of argument 2) 
A (Target) 

Called by: Compiled code 



Entry point IHEYGWV 

Function: 

POLY (A,X) for both A and X vectors of 
complex short floating-point. Result 
is complex short floating-point. 



Entry point IHEYGLS 

Function: 

As for IHEYGLV but X is scalar. 
Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A (Argument 2) 

A (Target) 

Called by: Compiled code 

IHEYGS 

Entry point IHEYGSV 

Function: 

POLY (A,X) for both A and X vectors of 
real short floating-point. Result is 
real short floating-point. 



Linkage : 

RA: A (Parameter list) 

Parameter list: 

A(ADV of argument 1) 
A(ADV of argument 2) 
A (Target) 

Called by: Compiled code 



Entry point IHEYGSS 

Function: 

As for IHEYGSV but X is scalar. 

Linkage : 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A (Argument 2) 

A (Target) 

Called by: Compiled code 



Linkage: 

RA: A( Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A(ADV of argument 2) 

A (Target) 

Called by: Compiled code 

Entry point IHEYGWS 

Function: 

As for IHEYGWV, but X is scalar. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 2) 

A (Argument 1) 

A (Target) 

Called by: Compiled code 
IHEYGX 

Calls: IHEDMA 
Entry point IHEYGXV 

Function: 

POLY (A,X) for both A and X vectors of 
complex fixed-point binary or decimal 
numbers. Result is complex short or 
long floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A(DED of argument 1) 

A(ADV of argument 2) 

A(DED of argument 2) 

A (Target) 

A(DED of target) 

Called by: Compiled code 
Entry point IHEYGXS 
Function: 

As for IHEYGXV, but X is scalar. 



Chapter 9: Module Summaries 155 



Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A(DED of argument 1) 

A (Argument 2) 

A(DED of argument 2) 

A (Target) 

A(DED of target) 

Called by: Compiled code 
IHEYG2 
Entry point IHEYGZS 

Function: 

As for IHEYGZV, but X is scalar. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A (Argument 2) 

A (Target) 

Called by: Compiled code 

Entry point IHEYGZV 

Function: 

POLY (A,X) for both A and X vectors of 
complex long floating-point numbers. 
Result is complex long floating-point. 

Linkage: 

RA: A (Parameter list) 
Parameter list: 

A(ADV of argument 1) 

A(ADV of argument 2) 

A (Target) 

Called by: Compiled code 



IHEZZC 
Calls: IHEZZF 

Entry point: IHEZZCA 



Function: 

To provide a SNAP dump with save-area 
trace and information about the PL/I 
files that are open. 



Linkage : 

RA: A (Parameter list) 

See source listing for parameter list. 



Called by: IHEDUM 



IHEZZF 



Entry point: IHEZZFA 



Function: 

To provide the save-area -trace that forms 
part of the output produced by IHEZZC. 



Linkage : 

RA: A (Parameter list) 

See source listing for parameter list. 

Called by: IHEZZC 
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APPENDIX A; SYSTEM MACRO INSTRUCTIONS 



The following table lists the system macro instructions used by the PL/I library and 
associates their use with individual library modules. 



System Macro 




Library 


Module 






ABEND 


IHEDUM, 


IHEERR 








ATTACH 


IHETSA 










CHAP 


IHECTT, 


IHEIGT, 


IHEITB, 


IHEITC, 


IHEITH, 


CHECK 


IHEITF, 


IHEITJ, 


IHEOPZ, 


IHEITB, 


IHEITC 


CHKPT 


IHECKP 










CLOSE 


IHECTT, 


IHECLS, 


IHECLT, 


IHEOPZ 




DCB 


IHEOPO, 


IHEOPZ 








DCBD 


IHECLT, 
IHEITJ, 


IHECTT, 
IHEOCL, 


IHEITB, 
IHEOCT, 


IHEITC, 
IHEOPO, 


IHEITD, 
IHEOPP, 


DELETE 


IHECLT, 


IHECTT, 


IHEESM, 


IHETEX 




DEQ 


IHECTT, 
IHETEX, 


IHEDDT, 
IHEITO 


IHEESM, 


IHEIBT, 


IHEITH, 


DETACH 


IHETSA 










DEVTYPE 


IHEOPO 










ENQ 


IHEDDT, 


IHEESM, 


IHEIBT, 


IHEITH, 


IHEITJ, 


ESETL 


IHEITD 










EXTRACT 


IHETSA, 


IHETEX, 


IHETOM, 


IHEPRT, 


IHEPTT 


FREEMAIN 


IHEBEG, 
IHEOCL, 


IHECLT, 
IHEOPZ, 


IHECTT, 
IHEOSW, 


IHEDSP, 
IHESAP, 


IHEIOG, 
IHETCV, 


FREEPOOL 


IHECLT, 


IHECTT, 


IHEOPQ, 


IHEOPZ 




GET 


IHEITD, 


IHEITG, 


IHEITP 






GETBUF 


IHEOPZ 










GETMAIN 


IHEBEG, 
IHEITF, 
IHESAP, 


IHEDSP, 
IHEITH, 
IHETCV, 


IHEERR, 
IHEITJ, 
IHESRT, 


IHEIGT, 
IHEITP, 
IHETSA 


IHEIOG, 
IHELSP, 


GETPOOL 


IHEOPP 










LINK 


IHEBEG, 


IHEDUM, 


IHEERR, 


IHEOCL, 


IHEOCT, 


LOAD 


IHEESM, 


IHEOPQ, 


IHETEX 






OPEN 


IHEOPP, 


IHEOPZ 








POST 


IHEDSP, 
IHETEA, 


IHEDUM, 
IHETEV, 


IHEIGT, 
IHETPR, 


IHEINT, 
IHETSA, 


IHEITB, 
IHETSW 



IHEITJ, IHEITO 



IHEITE, IHEITF, IHEITG, IHEITH, 
IHEOPQ, IHEOPZ 



IHEITJ, IHEOCT, IHEPTT, IHETSA, 



IHEOCT, IHEPTT, IHETEX, IHEITO 



IHEITB, IHEITC, IHELSP, IHEMSW, 
IHETSA, IHESRT, IHETSW 



IHEITB, IHEITC, IHEITD, IHEITE, 
IHEOPO, IHEOPP, IHEOPQ, IHEOPZ, 



IHEOPN, IHESRT, IHETSA 



IHEITC, IHEITH, IHEITJ, IHEOCT, 
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System Macro 




PUT 


IHEITD, 


PUTX 


IHEITD, 


READ 


IHEITB, 


RETURN 


IHECLT, 


SETL 


IHEITD 


SNAP 


IHEDUM 


SPIE 


IHEERR, 


STAE 


IHESAP, 


STIMER 


IHEOSI 


TIME 


IHEOSD, 


WAIT 


IHEDSP, 




IHEMSW. 


WRITE 


IHEITB, 




IHEITN, 


WTO 


IHEDSP, 


WTOR 


IHEDSP 


XCTL 


IHEOPN, 



Library Module 

IHEITG, IHEITP, IHETEX 

IHEITG 

IHEITE, IHEITF, IHEITH, IHEITJ, IHEITK f IHEITM, IHEITN, IHEITO 

IHECTT 



IHESAP, IHESRT, IHETSA 
IHESTA 

IHEOST 

IHEDUM, IHEIGT, IHEINT, IHEITB, IHEITC, IHEITE, IHEITH, IHEITJ, 
IHEOCT, IHEOSW, IHETEA, IHETEV, IHETPR, IHETSA, IHETSW 

IHEITC, IHEITE, IHEITF, IHEITH, IHEITJ, IHEOPZ, IHEITL, IHEITM, 
IHEITO 

IHEOCL, IHEOCT, IHEPRT, IHETOM, IHETEX, IHEPTT 



IHEOPO, IHEOPP 
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APPENDIX B: SYSTEM GENERATION 



System Generation Process 



IBM System/360 Operating System consists of 
libraries of program modules that can be 
united in a variety of combinations, 
according to options specified by the user. 
The user selects the programming options 
that meet his data processing requirements 
and conform to his machine facilities. The 
selected options are translated into 
program module requirements by the system 
generation process, the modules being 
compiled' into libraries that form the new 
operating system. 

The operating system is generated in two 
stages. First, a series of user-supplied 
macro instructions, which describe the 
machine facilities and programming options 
required, is written. From these, if no 
errors are found, a job stream is 
generated. In the next stage, the job 
stream is processed by the assembler, the 
linkage editor, and utility programs, to 
generate the libraries of modules which 
form the new operating system. The whole 
process is carried out using an existing 
operating system. The system generation 
process is described in IBM System/360 
Operating System; System Generation . 



PL/I Library System Generation 



All PL/I library modules are in load module 
form. Before system generation they exist 
on two libraries on the starter system: 

1. SYSl.PLlLIB. This PDS contains 

modules which are always required by 
a system using PL/I. 

2. SYS1.LM512. This contains both 

modules which are optionally 
required and modules which will be 
copied into SYSl.LINKLIB. 

Three PL/I library system macros are used, 
whose purpose is to produce COPY control 
cards for inclusion in the job stream. 

The first macro, SGIHE5LA, produces COPY 
control cards to copy modules from 
SYS1.LM512 into SYSl.LINKLIB. 

The second macro, SGIHE5PB, produces 
COPY control cards to copy the non-optional 
modules on the starter system SYSl.PLlLIB 
into the new SYSl.PLlLIB. 



The third macro, SGIHE5PC, tests for the 
COMPLEX arithmetic option. If it is 
present, COPY control cards are produced 
for modules dealing with complex arithmetic 
(about 30% of the total number). The macro 
then tests to see if the TIME and STIMER 
options have been requested and are 
available. If so, COPY control cards are 
produced for IHEOST and IHEOSI. If either 
or both of these options are not required, 
either or both of the dummy modules IHEMST 
and IHEMSI are renamed IHEOST and IHEOSI 
respectively and the appropriate COPY 
control cards are produced. Similarly, if 
the MULTIPLE WAIT option is not requested, 
the SINGLE WAIT module IHEMSW is renamed 
IHEOSW. 



STORAGE UTILIZATION AND SHARED LIBRARY 



Users of MVT and MFT control programs 
within the operating system may use the 
shared library feature in which parts of 
the re-entrant PL/I library are resident in 
the operating system. This feature enables 
certain modules to be shared between 
partitions or regions, thus greatly 
reducing the storage requirements of an 
individual PL/I program within a partition 
or region. 

Transfer of control between each 
partition and the resident library is 
achieved by means of two transfer vector 
modules, IHELTV and IHELTT. The module 
IHELTT is link- edited to the PL/I program 
and controls the calls to the resident 
library. IHELTV is link-edited to the 
resident library and controls the calls to 
the partition. Correlation between the two 
transfer vector modules is maintained by 
the PRV in each partition. Therefore, 
standardisation of the PRV is implicit in 
this feature. 

Practical implementation of the shared 
library feature necessitates separation of 
the library modules into functional groups. 
These groups are selected by options in the 
SYSGEN P LI LIB macro and are listed in Table 
1. This list includes those modules which 
may not be made resident (i.e., not 
shareable) and these are placed in Group 1. 
The storage management modules (group 2 or 
3) will always be included in a resident 
library. Tables 2 through 9 show the 
modules in their respective "packages" with 
their associated group numbers, whilst 
Table 10 is an alphabetical cross- reference 
list of the modules. 
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The Shared Library feature is made 
available at system generation time by 
specifying the required options in the 
PLlLIB macro. The specification of these 
options governs the generation of the 
resident load modules IHELTTA and IHELTVA. 



Table 1. 



Group 
No. 

|. + 

1 
2 
3 
4 
5 



Grouping of Modules (Shared 
Library Feature) 



6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 



Main Functions of the Group 



Non-shared modules 

Multi- tasking storage management 

Non-tasking storage management 

Error handler (ON-units) 

List processing and structure 

mapping 
Basic conversion package 
Edit conversions 
Complex conversions 
Bit string conversions 
Character string conversions 
Picture conversions 
Sterling conversions 
Optimization^ special conversions 
Bit string functions 
Character string functions 
•STRING* BIF and PV 
Real non- interleaved arrays 
Real interleaved arrays 
Complex non-interleaved arrays 
Complex interleaved arrays 
Real arithmetic operators 
Complex arithmetic operators 
Real short arithmetic functions 
Real long arithmetic functions 
Complex short arithmetic functions 
Complex long arithmetic functions 
Non-tasking data-directed I/O 
Non-tasking list- directed I/O 
Non-tasking edit-directed I/O 
Multi-tasking data-directed I/O 
Multi-tasking list-directed I/O 
Multi-tasking edit-directed I/O 
Non-tasking record I/O 
Multi-tasking record I/O 
Non-tasking record I/O wait 
Multi-tasking record I/O wait 






Note: The non-shared modules (Group 1) 
comprise those modules from the 
Housekeeping , String Function, and STREAM 
I/O Packages which cannot reside in the 
shared library. 

IHELTVA consists of the resident 
transfer vectors plus all the library 
modules selected for residency; the latter 
are link- edited to IHELTVA. IHELTTA 
consists of the non-resident transfer 
vectors. At initial program load time, the 
load module containing IHELTVA must be made 
resident in the link pack area of MVT or 
the resident access methods area of MFT 
control programs. 



Module IHELTTA must be included when a 
user wishes to create the shared library 
feature, and this may be achieved by means 
of the catalogued procedures discussed in 
IBM System/360 Operating System; PL/I (F) 
Programmer's Guide* 

For details of the PLlLIB macro 
instruction, see IBM System/360 Operating 
System; System Generation . Main storage 
requirements for this feature are discussed 
in IBM System/360 Operating System: Storage 
Estimates. 



Table 2. Housekeeping Package 







Sroup 


Number j 


t Module j 


Description 






_„. ■ 




— i 










1 1 


T] 


3 |4 |5 | 


j._- ^ 




—+—4 


— +— +-H 


| IHEABN | 


ABEND option 


x ! 






JIHETCVJ 


Control Variable 




x 1 




| IHETEA | 


Event Variable 




x I 




j IHETER | 


ON Field 




x 1 




|IHETEV| 


COMPLETION 




x 1 




j IHETPB j 


PRIORITY 




x 1 




| IHETPR j 


PRIORITY 




x 1 




JIHETSAJ 


Storage Manag.t 




x 1 




j IHETSE I 


FINISH 




x | 




|IHETSS| 


FINISH 




x 1 




j IHESAP I 


Storage Manag.t 






x I 1 1 


j IHEOSS | 


FINISH 






x I j 1 


j IHEOSE I 


EXIT 






x I 1 1 


j IHECKP 


Checkpoint 


x 






j IHEDSP 1 


Display 


IX 






jlHEDUM 


Dump 




IX | 


x 1 1 1 


j IHESRT 


Sort 


|X 






JIHEERR] 


Error 




IX j 


x 1 1 1 


jlHECFA 


ONLOC 






| X | j 


j IHECFB 


ONCODE 






|x I j 


j IHECNT 


ONLINE 






jx j j 


j IHEOCL 


OPEN/CLOSE 

(non-tasking) 






x i i i 


| IHEOCT 


OPEN/CLOSE 

(multitasking) 




IX 




| IHESRC 


ONSOURCE 






|X | | 


j IHESRD 


ONKEY 






|x 1 1 


j IHELSP 


List Processing 






1 |x j 


j IHESTR 


Structure Mapping 






1 IX j 


j IHEBES 


| Terminal Error 


|X 






j IHECFC 


| Mod 91 and 195 
| interrupts 


|x 






| IHEM91 


| Mod 91 and 195 
| errors 


|x 






| IHEMAI 


| Main 


|x 






j IHEMSI 


| No Timer 


jx 






j IHEMST 


| NO TIME 


|x 






j IHEMSW 


| WAIT I/O Event 


|X 






j IHEOSO 


j Date 




|X 


| X | | l 


j IHEOSI 


| Delay 


|x 






j IHEOST 


| Time 




|x 


|x I 1 1 


j IHEPTT 


| COPY Tasking 




|x 




j IHEPRT 


| COPY Non-tasking 






|x | I 1 


j IHERES 


| Restart 


|X 






JIHESIZ 


| Length PRV 


|X 






j IHESPR 


j SYSPRINT DCLCB 


|X 








L ■ ■ i ii m ■ ■ ■ ' i 


X 


X— 


L 1 l.-J 
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Table 3. 


Conversion Package 
















[ ' 










Group 


Number 






| Module 


Description 


|. 


_ T __- .— T — — 


— T<— — y— — y— 


_-_. T -._— T —^ 


| IHEDIA 




1 * 

-+ 

1 X 


1 7 

1 x 


8 


1 9 


1 10 I 
-+ +- 


11 I 
— ^ 


12 | 13 | 

1 x | 


F format director 




j IHEDIB 


E to Internal 




i x 






I x | 






| IHEDID 


B to Internal 




1 x 




1 x 








j IHEDIE 


Picture to Internal 




1 x 








x I 


x 1 I 


| IHEDIL 


A/B error 




1 x 












j IHEDIM 


C to Internal 




1 x 












j IHEDOA 


Internal to F/E 


1 x 


1 x 










1 X | 


j IHEOOB 


Internal to A 




1 x 












j IHEDOD 


Internal to B 




j x 












| IHEDOE 


Internal to Picture 




1 x 








x ! 


x 1 1 


| IHEDOM 


Internal to C 




1 x 












j IHEDMA 


Conversion director 


1 x 


1 x 


x 


1 x 


I x | 


x l 


x I I 


| IHEDNB 


Arithmetic to Bit 








1 x 








| IHED6N 


Bit to Arithmetic 








1 x 








j IHEDCN 


Bit to Character 










I x | 






| IHEDNC 


Arith to Character 










I x | 




1 x | 


j IHEKCA 


Valid Dec. Picture 












x 


1 x | 


| IHEKCB 


Valid Sterling Picture 














x I I 


| IHEKCD 


Valid Char. Picture 










I x | 






j IHEUPA 


Address Real Complex 






x 










| IHEUPB 


Address Imag. Complex 






X 






X 




j IHEVCA 


Arith. attributes 






X 










| IHEVCS 


Complex to Internal 






X 










j IHEVFA 


Binary to Decimal 


1 x 




X 






x I 




| IHEVFB 


Float to Fixed 


i x 




X 






x | 




j IHEVPC 


Float to Float 


1 x 














| IHEVFD 


Fixed to Float 


1 x 




X 






x ! 




j IHEVFE 


Float to Float 


1 x 














j IHEVKB 


Decimal to Packed 












x | 




| IHEVKC 


Sterling to Packed 














x 1 1 


| IHEVKF 


Packed to Fixed 












x ! 




j IHEVKG 


Packed to Sterling 














x 1 1 


| IHEVPA 


Decimal to Binary 


1 x 




X 






X 




| IHEVPB 


Decimal to F 


1 x 




X 






X 




j IHEVPC 


Packed to E 


1 X 




X 






X 




j IHEVPD 


Packed to Decimal 


1 x 




X 






X 




j IHEVPE 


E/F to Packed 


1 X 




X 






X 




| IHEVPF 


Decimal to Packed 


1 X 




X 






X 




j IHEVPG 


Fixed to Float 










I x | 






j IHEVPH 


Bit to Float 








1 x 








j IHEVSA 


Varying Bit 








1 x 








j IHEVSB 


Varying Bit/Character 








1 x 


I x t 






| IHEVSC 


Varying Character 










I x j 






j IHEVSD 


Varying Bit/Character 








1 x 


I x j 






| IHEVSE 


Character to Picture 










I x | 






j IHEVSF 


Bit to Picture 








1 x 


I x j 






j IHEVQA 


Float to Fixed 














1 x | 


j IHEVQB 


Decimal to Arithmetic 














1 x | 


j IHEVQC 


Arith. to E/F/Char. 














1 x j 


L— _——__. 


~— ~— — .— -- - i ,—.--————. 


-1— 


-J j 


_M_ __ 


_£—_—. 


-J i- 


J 


_A _ _J 
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Table U. 


STRING Function Package 


















-T- 




Group 


Number 


—\ 




| Module 


Description 




h 





-«r <r 


- — *—■ i— 


H 




^ 

j IHEBSA 


And 




-+- 


1 


I 1*» I 
H + 

I X | 


15 | 16 


H 






T 






| IHEBSO 


Or 








I x j 








j IHEBSN 


Not 








I x j 








| IHEBSC 


Compare 








I x j 








j IHEBSM 


Assign 








I X I 








| IHEBSK 


Concat, REPEAT 








I x | 








| IHEBSD 


Compare 








I x j 








j IHEBSS 


Compare, SUBSTR 








I x j 








| IHEBSI 


INDEX 








I x | 








j IHEBSF 


BOOL 








I X j 








| IHEBSV 


VERIFY 






X 










| IHEBST 


TRANSLATE 






X 










| IHECSK 


REPEAT 










x I 






j IHECSC 


Compare 










x I 






| IHECSM 


Assign, Fill HIGH/LOW 








x I 






j IHECSS 


SUBSTR 










x I 






| IHECSI 


INDEX 










x I 






| IHESTG 


STRING BIT 










I x 






j IHESTP 


STRING PV 










I x 






| IHECSV 


VERIFY 










x I 






| IHECST 


TRANSLATE 





.X. 





-J A. 


x I 

J 


.-j 




Table 5. 


ARRAY Function Package 








Table 6. 


Arithmetic Function Package 


r - i 
















| Group 


Number | 






Group Number | 


| Module 












| Module | 


Description 






"T" 


T 1 


p~™* — - JB ™^^™ " " j 




I 17 


18 


I 


19 


I 20| 






| 21 | 22 | 




.-__ — — . — — x — — -j- 


-+- 





h — 4 


j. — _ __. 


— — ____. 


.__—__ 4; — — J 


| IHEJXS 


Indexer j X 


X 




X 


X j 


| IHEXIB | 


X**N 


x I I 


j IHEJXI 


Indexer | 


X 






I x I 


j IHEXID | 


X**N 


I x | | 


j IHENL1 


ALL ANY j X 


X 




X 


X j 


| IHEAPD 


X**N 


x I I 


j IHENL2 


ALL ANY | 


X 






I X I 


| IHEXIS 


X**N 


x I I 


j IHESSF 


SUM | X 










j IHEXXS 


Shift 


I X | | 


| IHESMF 


SUM j 


X 








| IHEXIL 


X**Y 


X j | 


j IHESSG 


SUM | X 






X 




j IHEXXL 


X**Y 


I X | | 


| IHESMG 


SUM j 


X 






! x | 


j IHEMZU 


X*Y X/Y 


I I x j 


| IHESSG 


SUM | X 






X 




| IHEXIU 


X**N 


I | X | 


| IHESMH 


SUM j 


X 






I x I 


j IHEMZV 


X*Y X/Y 


I I x | 


| IHEPSF 


PROD | X 










j IHEXIV 


X**N 


I I x j 


| IHEPDF 


PROD j 


X 








j IHEMZW 


X*Y 


I I x | 


| IHEPSS 


PROD | X 










j IHEDZW 


X/Y 


I I x j 


j IHEPDS 


PROD j 


X 








j IHEXIW 


X**N 


I I x | 


j IHEPSL 


PROD | X 










| IHEXXW 


X**Y 


I I x j 


| IHEPDL 


PROD j 


X 








j IHEMZZ 


X*Y 


i i x j 


j IHEYGF 


POLY j X 


X 








j IHEDZZ 


X/Y 


I I x j 


j IHEYGS 


POLY | X 


X 








j IHEXIZ 


X**N 


I I x | 


j IHEYGL 


POLY j X 


X 








j IHEXXZ 


X**Y 


I I x j 


j IHESSX 


SUM j 






X 




j IHEMXB 


MAX MIN 


| X | | 


j IHESMX 


SUM j 








I x I 


j IHEMXD 


MAX MIN 


I x j | 


| IHEPSX 


PROD | 






X 




j IHEftDD 


ADD 


I x | | 


j IHEPDX 


PROD j 








I x I 


j IHEMXS 


MAX MIN 


I x j j 


| IHEPSW 


PROD j 






X 




j IHEMXL 


| MAX MIN 


I x | j 


| IHEPDW 


PROD j 








| X | 


j IHEMPU 


| MULTIPLY 


i i x j 


| IHEPSZ 


PROD | 






X 




| IHEDVU 


| DIVIDE 


I I x j 


j IHEPDZ 


PROD j 








I x | 


j IHEADV 


ADD 


I i X | 


j IHEYGX 


POLY | 






X 


I x | 


| I HEMP V 


| MULTIPLY 


i i x i 


| IHEYGW 


POLY | 






X 


i x j 


j IHEDW 


| DIVIDE 


I I x j 


j IHEYGZ 


POLY j 






X 


I x j 


I 




J. X J 


L__ —_—_—. 


. — -__^_— ..„_— ..—X- — —— ■ 




_JL. 


_., ■■— . 


1 J 
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Table 7. 
Module 



IHESQS 
IHEEXS 
IHELNS 
IHESNS 
IHETNS 
IHEATS 
IHESHS 
IHETHS 
IHEHTS 
IHEEPS 
IHESQL 
IHEEXL 
IHELNL 
IHESNL 
IHETNL 
IHEATL 
IHESHL 
IHETHL 
IHEHTL 
IHEEFL 
IHESQW 
IHEEXW 
IHELNW 
IHESNW 
IHETNW 
IHEATW 
IHESQZ 
IHEEXZ 
IHELNZ 
IHESNZ 
IHETNZ 
IHEATZ 
IHEA6U 
IHEABV 
IHEABW 
IHEABZ 



Mathematical Function Package 

Group Number 

Description J— t — r — t i 

23|24|25|26 

■+—+"+—+ < 



Table 8. 
i T 



RECORD I/O Package 



SQRT 

EXP 

LOG 

SIN COS 

TAN 

AT AN 

SINK COSH 

TANH 

ATANH 

ERF 

SQRT 

EXP 

LOG 

SIN COS 

TAN 

AT AN 

SINH COSH 

TANH 

ATANH 

ERF 

SQRT 

EXP 

LOG 

SIN COS SINH 

TAN TANH 

ATAN ATANH 

SQRT 

EXP 

LOG 

SIN COS SINH COSH 

TAN TANH 

ATAN ATANH 

ABS 

ABS 

ABS 

ABS 



COSH 



j Module j Description 



r 1 

| Group Number | 

V T—T—T-H 

| | 33|34|35|36| 

|IHEION|I/0 transmitter route| X | 

jlHEOSWJWait I/O EVENT j | JX j j 

| IHEOCL j OPEN/CLOSE | X j 

JIHEINTJI/O transmitter route | |X j j j 

jlHETSWJWait I/O EVENT | | 

j IHEOCT j OPEN/CLOSE | | X 



.— ___— X_— X__L— X— _J 



Table 9. 
r~ 



STREAM I/O Package 






Module 


Description 


IHEDDI 


Read Data 


IHEDDO 


Write/Convert Data 


IHEDDJ 


Array/address 


IHEDDP 


Array subscript 


IHEDDT 


Write Data Tasking 


IHEIBT 


Tasking PUT 


IHEIOA 


GET 


IHEIOB 


Non-tasking PUT 


IHEIOC 


GET string 


IHEIOD 


Datafield handler 


IHEIOF 


Logical records 


IHEIOP 


Page/Skip/Line 


IHEIOX 


Skip/Column 


IHELDI 


Read List 


IHELDO 


Write/Convert List 


IHETAB 


Page/Line default 



T "I 

Group Number 

T t T T T T i 

1 I 27 I 28 I 29 I 30 I 31 I 32 
-H + + -I + + i 



j.. 



X 

1- L_ 



X 
X 

X 
X 
X 
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Table 10. 


Cross 


-Reference to Library 
es and Groups 








Modul 


r ~ — r i 
| Module Name | selected Group 1 

L } ■ 


r t 

| Module Name | 


Selected Group j 


j IHEDVO 
j IHEDW 
j IHEDZW 


22 | 
22 | 
22 | 


| IHEABN 




1 | 


| IHEABU 




25 | 


| IHEEFL 


24,26 | 


1 IHEABV 




25 | 


j IHEEFS 


23,25 | 


j IHEABW 




26 | 


| IHEERD 


LINKLIB | 


j IHEABZ 




26 | 


j IHEERE 


LINKLIB | 


j IHEADD 




21 | 


j IHEERI 


LINKLIB j 


| IHEADV 




22 | 


j IHEERO 


LINKLIB j 


| IHEAPD 




21 | 


j IHEERP 


LINKLIB | 


| IHEATL 




24,26 | 


j IHEERR 


2,3 | 


| IHEATS 




23,25 | 


j IHEERT 


LINKLIB j 


j IHEATW 




25 | 


j IHEESM 


LINKLIB j 


j IHEATZ 




26 | 


j IHEEXL 


24,26 | 


j IHEBEG 




1 | 


| IHEEXS 


23,25 | 


| IHEBSA 




14 | 


j IHEEXW 


25 | 


j IHEBSC 




14 | 


j IHEEXZ 


26 | 


j IHEBSD 




14 j 


j IHEHTL 


24,26 | 


j IHEBSF 




14 | 


j IHEHTS 


23,25 | 


j IHEBSI 




14 | 


j IHEIBT 


30,31,32 | 


j IHEBSK 




14 | 


j IHEINT 


34 | 


j IHEBSM 




14 | 


| IHEIOA 


27,28,29,30,31,32 | 


| IHEBSN 




14 | 


j IHEIOB 


27,28,29 | 


| IHEBSO 




14 | 


| IHEIOC 


1 | 


j IHEBSS 




14 | 


j IHEIOD 


29,32 | 


j IHEBST 




1 | 


| IHEIOF 


27,28,29,30,31,32 | 


j IHEBSV 




1 | 


j IHEION 


33 | 


j IHECFA 




4 | 


j IHEIOP 


27,28,29,30,31,32 | 


j IHECFB 




4 j 


j IHEIOX 


29,32 | 


j IHECFC 




1 | 


j IHEITB 


LINKLIB j 


j IHECKP 




1 | 


j IHEITC 


LINKLIB j 


j IHECLT 




LINKLIB | 


j IHEITD 


LINKLIB j 


j IHECNT 




4 j 


j IHEITE 


LINKLIB j 


j IHECSC 




15 | 


j IHEITF 


LINKLIB j 


j IHECSI 




15 | 


| IHEITG 


LINKLIB | 


| IHECSK 




15 | 


j IHEITH 


LINKLIB j 


| IHECSM 




15 | 


| IHEITJ 


LINKLIB j 


| IHECSS 




15 | 


j IHEITK 


LINKLIB j 


j IHECST 




15 | 


j IHEITL 


LINKLIB j 


| IHECSV 




15 | 


j IHEITP 


LINKLIB | 


j IHECTT 




LINKLIB j 


j IHEJXI 


18,20 | 


j IHEDBN 




9 j 


j IHEJXS 


17,18,19,20 | 


| IHEDCN 




10 | 


| IHEKCA 


11,13 | 


| IHEDDI 




27.30 | 


j IHEKCB 


12 | 


j IHEDDJ 




27.30 | 


j IHEKCD 


10 | 


j IHEDDO 




27 | 


j IHELDI 


28,31 | 


j IHEDDP 




27,30 | 


j IHELDO 


28,31 | 


j IHEDDT 




30 | 


j IHELNL 


24,26 j 


| IHEDIA 




6,7,13 | 


j IHELNS 


23,25 | 


j IHEDIB 




7,10 | 


j IHELNW 


25 | 


| IHEDID 




7,9 | 


j IHELNZ 


26 | 


j IHEDIE 




7,11,12 | 


j IHELSP 


5 I 


j IHEDIL 




7 | 


j IHEMAI 


1 t 


j IHEDIM 




7 | 


j IHEMPO 


22 | 


j IHEDMA 




6,7,8,9,10,11,12 | 


j IHEMPV 


22 | 


| IHEDNB 




9 j 


j IHEMSI 


1 1 


| IHEDNC 




10,13 | 


j IHEMST 


1 | 


j IHEDOA 




6,7,13 | 


j IHEMSW 


1 1 1 


j IHEDOB 




7 j 


j IHEMXB 


21 | 


| IHEDOD 




7 | 


j IHEMXD 


1 21 | 


j IHEDOE 




7,11,12 | 


| IHEMXL 


1 21 | 


| IHEDOM 




7 I 


j IHEMXS 


21 | 


j IHEDSP 




1 | 


j IHEMZO 


! 22 | 


j IHEDUM 




2,3 | 


L 


L — — — -J 


L— _„_____ 


JL~ 


——__———————_-.— .j 
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| Module 




Module 




j Name 


| Selected Group j j 


Name 


Selected Gr 


L ____________ 






.—__--— _»_^— -.»-^ 


j IHEMZV 


| 22 | 


IHETAB 


27,28,30,31 


| IHEMZW 


I 22 | 


IHETCV 


2 


j IHEMZZ 


I 22 | 


IHETEA 


2 


| IHEM91 


I 1 I 


IBETER 


2 


| IHENL1 


| 17,18,19,20 | ! 


IHETEV 


2 


j IHENL2 


I 18,20 | 


IHETEX 


LINKLIB 


| IHEOCL 


| 3,33 | 


IHETHL 


24,26 


j IHEOCT 


I 2,34 | 


IHETHS 


23,25 


j IHEOPN 


| LINKLIB j 


IHETNL 


24,26 


j IHEOPO 


| LINKLIB j 


IHETNS 


23,25 


j IHEOPP 


| LINKLIB j 


IHETNW. 


25 


j IHEOPQ 


| LINKLIB | 


IHETNZ 


26 


| IHEOPZ 


LINKLIB j 


IHETOM 


LINKLIB 


| IHEOSD 


2,3 | 


IHETPB 


2 


| IHEOSE 


3 | 


IHETPR 


2 


| IHEOSI 


I 1 I 


IHETSA 


2 


j IHEOSS 


I 3 | 


IHETSE 


2 


j IHEOST 


I 2.3 | 


IHETSS 


2 


j IHEOSW 


I 35 | 


IHETSW 


36 


| IHEPDF 


| 18 | 


IHEOPA 


8 


| IHEPDL 


18 | 


IHEUPB 


8,11 


| IHEPDS 


! 18 | 


IHEVCA 


8 


j IHEPDW 


I 20 | 


IHEVCS 


8 


j IHEPDX 


I 20 | 


IHEVFA 


6,8,11 


j IHEPDZ 


I 20 | 


IHEVFB 


6,8,11 


j IHEPRT 


I 3 I 


IHEVFC 


6 


j IHEPSF 


I 17 | 


IHEVFD 


6,8,11 


I IHEPSL 


17 | 


IHEVFE 


6 


| IHEPSS 


! 17 | 


IHEVKB 


11 


j IHEPSW 


19 | 


IHEVKC 


12 


| IHEPSX 


19 | 


IHEVKF 


11 


| IHEPSZ 


19 | 


IHEVKG 


12 


| IHEPTT 


2 | 


IHEVPA 


6,8,11 


j IHERES 


1 I 


IHEVPB 


6,8,11 


| IHESAP 


3 | 


IHEVPC 


6,8,11 


| IHESHL 


24,26 | 


IHEVPD 


6,8,11 


j IHESHS 


23,25 | 


IHEVPE 


6,8,11 


| IHESIZ 


2.3 | 


IHEVPF 


6,8,11 


j IHESMF 


18 | 


IHEVPG 


10 


j IHESNG 


18,20 | 


IHEVPH 


9 


j IHESMH 


18,20 | 


IHEVQA 


13 


| IHESMX 


20 | 


IHEVQB 


13 


j IHESNL 


24,26 | 


IHEVQC 


13 


| IHESNS 


23.25 J 


IHEVSA 


9 


j IHESNW 


25 | 


IHEVSB 


9,10 


j IHESNZ 


26 | 


IHEVSC 


10 


| IHESPR 


1 I 


IHEVSD 


9,10 


j IHESQL 


24,26 | 


IHEVSE 


10 


| IHESQS 


23,25 | 


IHEVSF 


9,10 


j IHESQW 


25 | 


IHEVTB 


6 


| IHESQZ 


26 | 


IHEXIB 


21 


j IHESRC 


4 j 


IHEXIC 


21 


| IHESRD 


4 j 


IHEXIL 


21 


j IHESRT 


1 | 


IHEXIS 


21 


| IHESSF 


17 | 


IHEXIO 


22 


j IHESSG 


17,19 | 


IHEXIV 


I 22 


j IHESSH 


17,19 | 


IHEXIW 


22 


| IHESSX 


19 | 


IHEXIZ 


I 22 


j IHESTA 


LINKLIB j 


IHEXXL 


21 


j IHESTG 


16 | 


IHEXXS 


I 21 


j IHESTP 


16 | 


IHEXXW 


I 22 


j IHESTR 


5 | 


IHEXXZ 


| 22 


j IHESUB ! 


LINKLIB j 


IHEYGF 


I 17,18 



..J 
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Module 






H- 


Name 


-+- 


Selecte 


IHEYGL 


17,18 




IHEYGS 




17,18 




IHEYGW 




1-7,18 




IHEYGX 




19,20 




IHEYGZ 




19,20 




IHEZZA 




LINKLIB 




IHEZZB 




LINKLIB 




IHEZZC 




LINKLIB 




IHEZZF 




LINKLIB 






166 



APPENDIX C: PL/I OBJECT PROGRAM PSEUDO-REGISTERS 



PL/I object programs require 
pseudo-registers (symbolic name format 
I HE Q xxx ) , some of which are defined by the 
compiled program, others by the library 
modules. During execution of a program 
register PR always points to the base of 
the PRV (see 'Pseudo-Register Vector', 
Chapter 2). 

IHEQADC 

Pointer to a list of address constants 
for use by the I/O routines: for 
non-multitasking the list is in IHESA, for 
multitasking in IHETSA. 

IHEQATV 

Contains the address of the task 
variable for the current task. 

IHEQCFL 

The current-file pseudo-register, 
8-bytes, word aligned. Used by STREAM I/O 
modules for implicit communication of the 
file currently being operated upon; see 
•Current Pile' in Chapter 3. 

IHEQCTS 

Contains the address of the save area 
for the control task in a multiprogramming 
environment. 

IHEQERR 

Serves as a parameter list when calling 
IHEERRB. The code associated with the ON 
condition to be raised is placed into 
IHEQERR. See 'ON Conditions' in Chapter 6. 

IHECEVT 

The anchor cell for the incomplete I/O 
event variables in a given task. When 
IHEQEVT contains zero, no I/O event 
variable in the task is incomplete. 

IHEQFOP 

The anchor cell of the chain linking the 
FCBs for the files opened in a given task. 
When IHEQFOP is zero, none of the files 
opened in this task are still open. See 
•File Control Block' in Chapter 3. 

IHEQFVD 

Pointer to the Free VDA module: IHESAFD 
for non-multitasking, IHETSAF for 
multitasking. 



IHEQINV 



Contains the invocation count, and is 
updated by a library module each time a DSA 
is obtained. 



IHEQLCA 



Pointer to the current generation of the 
library communication area; see 'Library 
Workspace' in Chapters 2 and 4. 



IHEQLPR 

Length of the pseudo- register vector. 

IHEQLSA 

Pointer to the first save area in LWS, 
which serves two purposes: (1) the save 
area provided by the error-handling 
routines for an on-unit, and (2) an area 
where initial task information is saved 
(PICA, program mask, etc.). See Chapter 4. 

IHEQLWO. IHEQLW1. IHEQLW2. IHEQLW3. IHEQLW4 

Pointers to the various levels of 
library workspace ; see 'Library Workspace* 
in Chapters 2 and 4. 

IHEQLWE 

Pointer to the save area and workspace 
used by the error- handling routines when 
calling other library routines (not an 
on-unit) . 

IHEQLWF 

Pointer to the reserved area attached to 
the current LWS. Used for optimization in 
storage management. See 'Object-time 
Optimization' in Chapter 4. 

IHEQRTC 

Contains the return code used in the 
normal termination of a PL/I program. (See 
Chapter 4.) 

IHEQSAR 

Contains an environment count used by 
the display modification module (IHESAR) 
when on-units and entry parameter 
procedures are used in prologues and 
epilogues. 
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IHEQ5FC 

Pointer to free- core within first block 
of storage obtained by the task 
initialization library module (IHESA); see 
Chapter 4. 

IHBOSLA 

Pointer to the latest element in the DSA 
chain allocated by the storage management 
routines. The area may be a DSA or a VDA. 
see chapter 4. 

IHEQSPR 

The file register for SYSPRINT, the name 
being standardized to allow usage of the 
same FCB for both the source program and 
the library modules. See * Standard Files', 
and 'File Addressing Technique' in Chapter 
3. 



>TTl 


(cont.) IHEQINV 


TT2 


LCA 


TT3 


LSA 


TT4 


LWO 


TT5 


LW1 


TV1 


LW2 


TV2 


LW3 


TV3 


LWft 


TVH 


LWE 


TV5 


LWF 


LPR 


RTC 


ADC 


SAR 


ATV 


SFC 


CFL 


SLA 


CTS 


SPR 


ERR 


TIC 


EVT 


VDA 


FOP 


XLV 


FVD 


TCA 



IHEQTV1 through IHEQTV5 



IHEOTCA 

Used only in multitasking, 
address of the tasks TCA. 

IHEQTIC 



Contains the 



Contains the pseudo entry points for the 
transfer vector tables in resident main 
storage when the Shared Library feature is 
enabled. 



Contains the task invocation count, 
which is used in multitasking in the 
freeing of controlled storage. 

IHEOTTl through IHEQTT5 

Contains the pseudo entry points for the 
transfer vector tables held in the 
partition when the Shared Library feature 
is enabled. 

NOTE: The Shared Library feature, involving 
the pseudo-registers above, must have the 
common section of the PRV formatted in the 
following sequences 



IHEQVDA 



Pointer to the Get VDA module: in 
non-multitasking set (in IHESAP) to IHESADF; 
in multitasking, set (in IHETSAM) to 
IHETSAW. 



IHEQXLV 

The anchor cell for the exclusive blocks 
created in a given task. When IHEQXLV 
contains zero, the task has no exclusive 
blocks. 
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APPENDIX D: LIBRARY MACRO INSTRUCTIONS 



IHELIB 

Operands: None 

Result: 

Definitions of LWS pseudo- registers. 
Lengths of save areas in LWS. 
Format of the library communication area. 
Definitions of save area offsets. 
Definitions of standard register 
assignments. 

IHEEVT 

Operands: None 

Result: 

Definitions of the event variable and its 
flags. 

IHEPRV 

Operands: 

A three-character code denoting the last 

three letters of a pseudo- register name 

(default: LCA) 
A code denoting a general register 

(default: WR) 
A keyword parameter OP=XX, where XX is an 

RX instruction (default: L) 

Result: 

The RX operation is performed on the 
pseudo-register. This macro is 
generally used to store the contents of 
a pseudo- register in a general 
register. 

IHESDR 

Operands : 

A three- character code denoting a 
workspace level (default: LWO) 

A code denoting a general register other 
than register DR (default: WR) 



Result: 



The address of the required workspace 
level is put into register DR. 



IHEXLV 

Operands: None 

Result: 

Definition of exclusive block and its 
flags. 

IHEZAP 

Operands : None 

Result: 

Definitions of I/O pseudo-registers. 
Definitions of the file control block and 

its flag bytes. 
Definition of the declare control block. 
Definitions of various I/O address 

constants, parameters, operations and 

options. 
Definitions of the I/O control block and 

its flag bytes. 
Definitions of the I/O event variable and 

its flags. 

IHEZZZ 

Operands : DUMP/none 

Result: 

If the operand is omitted, or is not 
DUMP, a full DSECT is generated. If 
the operand is DUMP, only the parameter 
list for IHEZZC is defined as a DSECT. 

Used only by IHEDUM, IHEZZC, IHEZZF. 
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APPENDIX E: PL/I LIBRARY INTERNAL ERROR CODES AND MESSAGES 



Among the errors that occur during program 
execution are errors that are covered by 
PL/I-defined conditions. If one of these 
occurs, an appropriate error code is passed 
to IHEERR in pseudo- register IHEQERR. This 
code is a 4-digit hexadecimal number. The 
two high-order digits denote the PL/I 
condition (Figure 19); the others denote 
the errors associated with that condition. 



— i 



j Code 


I 


Condition j 


y 


+ _ 


.] 


1 10 


I 


STRINGRANGE j 


| 18 


I 


OVERFLOW j 


| 20 


I 


SIZE j 


| 28 


I 


FIXEDOVERFLOW j 


| 30 


I 


SUBSCRIPTRANGE | 


| 38 


I 


CHECK (label) | 


| 40 


I 


CONVERSION | 


j 48 


I 


CHECK (variable) | 


I 50 


I 


CONDITION (identifier) j 


| 58 


I 


FINISH / j 


| 60 


I 


ERROR | 


| 68 


I 


ZERODIVIDE j 


I 70 


I 


UNDERFLOW j 


| 78 


I 


AREA | 


| 88 


I 


NAME | 


| 90 


I 


RECORD | 


| 98 


I 


TRANSMIT | 


| A0 


I 


I/O SIZE | 


I A8 


I 


KEY j 


| B0 


I 


ENDPAGE | 


| B8 


I 


ENDFILE | 


| CO 


I 


I/O CONVERSION | 


j C8 

L__ ________ 


I 


UNDEFINEDFILE | 

i 


Figure 49. 


Internal Codes for ON Condition 




Entries 



If system action is required, an error 
message will be printed. The messages 
relating to the errors for the PL/I 
conditions are given here. 

Error code Message 



1000 


STRINGRANGE 


1800 


OVERFLOW 


2000 


SIZE 


2800 


FIXEDOVERFLOW 


3000 


SUBSCRIPTRANGE 


4000 


CONVERSION 


4001 


CONVERSION ERROR IN F-FORMAT 




INPUT 



4002 

4003 
4004 
4005 
4006 

4007 

4008 

4009 

5000 
5800 
6000 
6800 
7000 
7800 
7801 

7802 

8800 
9000 
9001 

9002 

9003 

9004 
9800 
9801 



CONVERSION ERROR IN E-FORMAT 
INPUT 



CONVERSION ERROR IN B- FORMAT 
INPUT 

ERROR IN CONVERSION FROM 
CHARACTER STRING TO ARITHMETIC 

ERROR IN CONVERSION FROM 
CHARACTER STRING TO BIT STRING 

ERROR IN CONVERSION FROM 
CHARACTER STRING TO PICTURED 
CHARACTER STRING 

CONVERSION ERROR IN P-FORMAT 
INPUT (DECIMAL) 

CONVERSION ERROR IN P-FORMAT 
INPUT (CHARACTER) 

CONVERSION ERROR IN P-FORMAT 
INPUT (STERLING) 

CONDITION 

FINISH 

ERROR 

ZERODIVIDE 

UNDERFLOW 

AREA SIGNALED 

AREA CONDITION RAISED IN 
ASSIGNMENT STATEMENT 

AREA CONDITION RAISED IN 
ALLOCATE STATEMENT 

UNRECOGNIZABLE DATA NAME 

RECORD CONDITION SIGNALED 

RECORD VARIABLE SMALLER THAN 
RECORD SIZE 

RECORD VARIABLE LARGER THAN 
RECORD SIZE 

ATTEMPT TO WRITE ZERO LENGTH 
RECORD 

ZERO LENGTH RECORD READ 

TRANSMIT CONDITION SIGNALED 

PERMANENT OUTPUT ERROR 
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9802 PERMANENT INPUT ERROR 

A800 KEY CONDITION SIGNALED 

A801 KEYED RECORD NOT FOUND 

A802 ATTEMPT TO ADD DUPLICATE KEY 

A803, KEY SEQUENCE ERROR 

A8CW KEY CONVERSION ERROR 

A805 KEY SPECIFICATION ERROR 

A806 KEYED RELATIVE RECORD/TRACK 
OUTSIDE DATA SET LIMIT 

A807 NO SPACE AVAILABLE TO ADD 
KEYED RECORD 

B800 END OF FILE ENCOUNTERED 

C8 00 UNDEFINEDFILE CONDITION 
SIGNALED 

C801 FILE ATTRIBUTE CONFLICT AT 
OPEN 



C802 FILE TYPE NOT SUPPORTED 

C803 BLOCKSIZE NOT SPECIFIED 

C804 CANNOT BE OPENED (NO DD CARD) 

C805 ERROR INITIALIZING REGIONAL 
DATA SET 

C806 CONFLICTING ATTRIBUTE AND 
ENVIRONMENT PARAMETERS 

C807 CONFLICTING ENVIRONMENT AND/OR 
DD PARAMETERS 

C808 KEY LENGTH NOT SPECIFIED 

C809 INCORRECT BLOCKSIZE AND/OR 
LOGICAL RECORD SIZE 

C80A LINESIZE GT IMPLEMENTATION 
DEFINED MAXIMUM LENGTH 

C80B CONFLICTING ATTRIBUTE AND DD 
PARAMETERS 
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APPENDIX F: DUMP INDEX 



The dump index provided by the subroutines 
IHEZZA, IHEZZB, and IHEZZC contains 
information about: 

SYSPRINT buffers 

Files currently open 

Current file 

Save areas 

On-units f interrupts and other details 

This information is output to a file called 
PL 1 DUMP. 



Save Areas 



A trace-back through the save-area chain 
provides the following addresses: 

A(A11 save areas, including the 
library save areas) 



A (Current LCA) 

A(PRV VDA) 
ACVDA for LWS2) 



SYSPRINT Buffers 



The contents of each buffer are given, in 
EBCDIC- If U-format records are used, the 
contents of the intermediate buffer used by 
the library are also printed. 



Files Currently Open 

File name 

A(DCLCB) 

A(FCB) 

A(DCB) 

File-register offset in PRV 



Other Information 



If a CALL was made: A (CALL) 

A( Procedure) or 
A (Entry point of 
library module) 



If a BEGIN block was entered: A (Entry 
point) 



If a program interrupt occurs: A (Interrupt) 



If ah on- unit was entered: Type of on-unit. 
If this on-unit is the error on-unit and 
was entered as a result of system 
action, the condition causing the system 
action is given. 



Current File 



If IHEDMA occurs in the trace- back: The 
names of the modules used in the 
conversion are given. 



I/O Files: File name 
A(DCLCB) 
A(FCB) 
A(DCB) 

STRING Files: A(SDV) 



The statement number (if it exists) is 
given. 



The following program illustrates the 
use of the dump index: 
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TDUMP: PROC OPTIONS (MAIN); 



1 
2 
3 
U 
6 
8 
9 
10 

11 
12 
13 
14 
15 
16 
17 
18 



TDUMP: PROC OPTIONS (MAIN) ; 

DCL A CHAR(a)INIT( , ABCD t ); 
DCL IHESARC ENTRY (FIXED BINARY(31)); 

ON ERROR CALL IHEDUMP; 

ON CONV CALL CONVPROC; 
CALL IHESARC (20); 

PUT LIST ('THIS IS THE FIRST LINE 1 ); 

PUT SKIP LISTCTHIS IS THE SECOND 

LINE' ) ; 

OPEN FILE(XYZ) OUTPUT; 

BEGIN; 

X=A; /* CONV ERROR */ 

END ; 
CONVPROC:PROC; 

DCL Y(-32768:-32768,-32768:-32768) CHAR(l); 

Z=Y(32767 f 32767) ; /* ADDRESSING ERROR */ 

END TDUMP; 

The addressing error only occurs if this program is the only one being executed. 
The dump index produced for this program is: 

* * * PL/I F-COMPILER 5TH VERSION ♦ IHEDUMP * * * 



* * * SYSPRINT BUFFERS 
BUFFER 01 

HE FIRST LINE " U YA 3 

BUFFER 02 



R IHEOPNA O O 



IHE804I ADDRESSING INTERRUPT IN STATEMENT 00017 AT OFFSET +000B4 
FROM ENTRY POINT CONVPROC 



*** FILES CURRENTLY OPEN 

XYZ 
SYSPRINT 



DCLCB 00A488 FCB 03EB10 DCB 03EB70 PR OFFSET 01C 
DCLCB 00AUC0 FCB 03EBD0 DCB 03EC00 PR OFFSET 020 



*** CHAIN BACK THROUGH SAVE AREAS 

03F9B0 DSA FOR ERR ON-UNIT 

03DF10 SECONDARY LIBRARY WORKSPACE 

03DF20 SAVE AREA FOR LIBRARY 

03F690 SAVE AREA FOR LIBRARY 

03FUC8 SAVE AREA FOR LIBRARY 

03F8D8 DSA FOR PROC CONVPROC 

03F828 DSA FOR CONV ON-UNIT 

03F338 SECONDARY LIBRARY WORKSPACE 

03F348 SAVE AREA FOR LIBRARY 

03F018 SAVE AREA FOR LIBRARY 



CALLS IHEDUMP FROM 00A1FA (STMT 5) 

CALLS 00A19C FROM 00CA3E LCA AT 03E3] 

CALLS 00A522 FROM 00CA04 LCA AT 03F730 

INTERRUPT AT 00AF46 LCA AT 03F730 

CALLS 00AEF0 FROM 00A318 (STMT 17) 

CALLS 00A26U FROM 00A25E (STMT 7) 

CALLS 00A200 FROM 00CA3E LCA AT 03F730 

CALLS 00A522 FROM 00CA04 LCA AT 03F0B8 
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03EDB8 SAVE AREA FOR LIBRARY CALLS 00C728 FROM 00B9CA LCA AT 03F0B8 

03FE50 SAVE AREA FOR LIBRARY CALLS 00B8D0 FROM 00AF06 LCA AT 03F0B8 

03F290 DSA FOR BEGIN CALLS 00AEF0 FROM 00A186 (STMT 13) 

03F1B0 DSA FOR PROC TDUMP ENTERS BEGIN AT 00A138 

03EC60 PRV - PSEUDO REGISTERS START AT 03EC68 

03FFB»» EXTERNAL SA CALLS 00A020 

*** END OF OUTPUT 

When V-format records are used, the first nine data characters of one of the SYSPRINT 
buffers may be blanked out. 

If there had been a current file, this would have appeared after the section on 'Files 
Currently Opened*. 
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APPENDIX 6: LENGTHS AND LOCATIONS OF MODULES 



The following list comprises all the 
library modules provided for Version 5 of 
the PL/I (F) Compiler. As each module is 
aligned on a doubleword boundary in main 
storage, the length of each module given 
here has been rounded up to a multiple of 
eight. Some of the modules are not 
required by Version 5 V but are included for 
compatibility with previous versions; 
numbers in parentheses after the names of 
these modules indicate the versions that do 
use them. The modules marked * reside in 
the link library (SYSl.LINKLIB) ; all other 
modules are in SYSl.PLlLIB. 



Module 



Length 



IHEABN 


12 


IHEABU 


224 


IHEABV 


504 


IHEABW 


128 


IHEABZ 


128 


IHEADD 


216 


IHEADV 


96 


IHEAPD 


360 


IHEATL 


480 


IHEATS 


368 


IHEATW 


288 


IHEATZ 


288 


IHEBEG 


128 


IHEBSA 


296 


IHEBSC 


272 


IHEBSD 


192 


IHEBSF 


480 


IHEBSI 


296 


IHEBSK 


472 


IHEBSM 


384 


IBEBSN 


192 


IHEBSO 


312 


IHEBSS 


240 


IHEBST 


584 


IHEBSV 


408 


IHECFA 


160 


IHECFB 


584 


IHECFC 


88 


IHECKP 


184 


* IHECLS (1,2,3) 


992 


* IHECLT 


1368 


IHECNT 


72 


IBECSC 


200 


IHECSI 


168 


IHECSK 


320 


IHECSM 


280 


IHECSS 


224 


IHECST 


304 


IHECSV 


198 


* IHECTT 


1800 


IHEDBN 


360 


IHEDCN 


496 


IHEDDI 


1264 


IHEDDJ 


448 


IHEDDO 


648 


IHEDDP 


640 



Module Length 

IHEDDT 760 

IHEDIA 784 

IHEDIB 280 

IHEDID 448 

IHEDIE 456 

IHEDIL 48 

IHEDIM 528 

IHEDMA 248 

IHEDNB 264 

IHEDNC 648 

IHEDOA 520 

IHEDOB 328 

IHEDOD 296 

IHEDOE 224 

IHEDOM 584 

IHEDSP 648 

IHEDUM 420 

IHEDVU 488 

IHEDW 576 

IHEDZW 104 

IHEDZZ 104 

IHEEFL 688 

IHEEFS 416 

* IHEERD 720 

* IHEERE 1704 

* IHEERI 896 

* IHEERN (1,2) 4096 

* IHEERO 856 

* IHEERP 1272 
IHEERR 1824 

* IHEERS (1) 848 

* IHEERT 712 

* IHEESM 1776 

* IHEESS (2) 1960 
IHEEXL 456 
IHEEXS 248 
IHEEXW 136 
IHEEXZ 136 
IHEHTL 264 
IHEHTS 176 
IHEIBT 576 
IHEIGT (1,2,3,4) 1344 
IHEINT 440 
IHEIOA 360 
IHEIOB 480 
IHEIOC 288 
IHEIOD 672 
IHEIOE (1,2,3) 176 
IHEIOF 736 
IHEIOG (1,2,3,4) 1104 
IHEIOH (2) 200 

* IHEIOJ (2,3) 1992 
IHEION 248 
IHEIOP 496 
IHEIOX 336 

* IBEITB 3784 

* IHEITC 2640 

* IHEITD 2280 

* IHEITE 1760 

* IHEITF 1856 
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Module 


Lenqth 


* IHEITG 


1168 


* IHEITH 


2616 


* IHEITJ 


2656 


* IHEITK 


736 


* IHEITL 


536 


* IHEITM 


2720 


* IHEITN 


2400 


* IHEITO 


2590 


* IHEITP 


936 


IHEJXI 


320 


IHEJXS 


104 


IHEKCA 


1560 


IHEKCB 


1464 


IHEKCD 


240 


IHELDI 


2112 


IHELDO 


1048 


IHELNL 


344 


IHELNS 


264 


IHELNW 


216 


IHELNZ 


224 


IHELSP 


1064 


IHELTT 


Varying 


IHELTV 


Varying 


IHEM91 


344 


IHEMAI 


8 


IHEMPU 


312 


IHEMPV 


288 


IHEMSI 


32 


IHEMST 


32 


IHEMSW 


136 


IHEMXB 


152 


IHEMXD 


120 


IHEMXL 


96 


IHEMXS 


96 


IHEMZU 


344 


IHEMZV 


672 


IHEMZW 


64 


IHEMZZ 


64 


IHENL1 


280 


IHENL2 


192 


IHEOCL 


1352 


IHEOCT 


2200 


* IHEOPN 


984 


* IHEOPO 


1992 


* IHEOPP 


2008 


* IHEOPQ 


1368 


* IHEOPZ 


992 


IHEOSD 


216 


IHEOSE 


80 


IHEOSI 


72 


IHEOSS 


56 


IHEOST 


88 


IHEOSW 


1064 


IHEPDF 


144 


IHEPDL 


88 


IHEPDS 


88 


IHEPDW 


120 


IHEPDX 


288 


IHEPDZ 


120 


IHEPRT 


672 


IHEPSF 


176 


IHEPSL 


72 


IHEPSS 


72 


IHEPSW 


96 


IHEPSX 


272 


IHEPSZ 


96 



Module 



Lenqth 



IHEPTT 


792 


IHERES 


104 


IHESAP 


2488 


IHESHL 


240 


IHESHS 


168 


IHESIZ 


16 


IHESMF 


136 


IHESMG 


128 


IHESHH 


128 


IHESMX 


240 


IHESNL 


408 


IHESNS 


32C 


IHESNW 


312 


IHESNZ 


360 


IHESQL 


160 


IHESQS 


168 


IHESQW 


280 


IHESQZ 


296 


IHESPR 


32 


IHESRC 


344 


IHESRD 


128 


IHESRT 


1360 


IHESSF 


184 


IHESS6 


104 


IHESSB 


104 


IHESSX 


232 


IHESTA 


1128 


IHESTG 


1384 


IHESTP 


1440 


IHESTR 


1592 


IHESUB 


16 


IHETAB 


16 


IHETCV 


216 


IHETEA 


248 


IHETER 


272 


IHETEV 


256 


IHETEX 


1464 


IHETHL 


248 


IHETHS 


200 


IHETNL 


320 


IHETNS 


256 


IHETNW 


176 


IHETNZ 


176 


IHETOM 


512 


IHETPB 


56 


IHETPR 


272 


IHETSft 


5720 


IHETSE 


88 


IHETSS 


72 


IHETSW 


1520 


IHEUPA 


232 


IHEUPB 


232 


IHEVCA 


272 


IHEVCS 


480 


IHEVFA 


232 


IHEVFB 


240 


IHEVFC 


40 


IHEVFD 


104 


IHEVFE 


32 


IBEVKB 


784 


IHEVKC 


720 


IHEVKF 


1624 


IHEVKG 


1248 


IHEVPA 


352 


IHEVPB 


424 


IHEVPC 


496 
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Module 



Length 



IHEVPD 


264 


IHEVPE 


616 


IHEVPF 


72 


IHEVPG 


560 


IHEVPH 


184 


IHEVQA 


224 


IfiEVQB 


1008 


IHEVQC 


616 


IHEVSA 


320 


IHEVSB 


208 


IHEVSC 


176 


IHEVSD 


416 


IHEVSE 


352 


IHEVSF 


240 


IHEVTB 


136 


I HEX IB 


136 


IHEXID 


136 


IHEXIL 


152 


IHEXIS 


152 


IHEXIU 


144 


IHEXIV 


192 


IHEXIW 


256 


IHEXIZ 


256 


IHEXXL 


152 


IHEXXS 


144 


IHEXXW 


280 


IHEXXZ 


280 


IHEYGF 


432 


IUEYGL 


240 


IHEYGS 


240 


IHEYGW 


280 


IHEYGX 


704 


IHEYGZ 


280 


* IHEZZA (3) 


1296 


* IHEZZB (3) 


1704 


* IHEZZC 


3008 


* IHEZZF 


1600 
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APPENDIX H: COMPILER-GENERATED CONTROL BLOCKS 



This appendix describes all the compiler-generated control blocks used by the PL/I 
Library except the DCLCB and the OCB f which are described in Appendix I (Input/Output 
Control Blocks). All offsets are given in hexadecimal form. 



Appendix H: Compiler-Generated Control Blocks 181 



182 



ARRAY DOPE VECTOR (ADV) 



2 3 7 8 



r t- 

BtOf j 



15 16 
Virtual origin 
Multiplier x 



31 



Multiplier n 



Upper bounds 



+-- 



Lower bound*. 



Upper bound n 



I 

■+-- 
I 



Lower bound. 



■H 



Figure 50. Format of the Array Dope Vector 
(ADV) 

This control block contains information 
required in the derivation of elemental 
addresses within an array data aggregate. 
The ADV is used for three functions within 
the library: 

1. Given an array, to step through the 
array in row- major order. 

2. Given the subscript values of an array 
element, to determine the element 
address. 

3. Given an element address, to determine 
its subscript values. 

Within PL/I implementation, arrays are 
stored in row-major order, upward in 
storage. The elements of an array are 
normally in contiguous storage; if the 
array is a member of a structure, its 
elements may be discontiguous. Such 
discontiguity, however, is transparent to 
algorithms which employ an array dope 
vector . 

The ADV contains (2n ♦ 1) 3 2- bit words, 
where n is the number of dimensions of the 
array. The number of dimensions in the 
array is not described within the ADV, but 
is passed to the library as an additional 
argument. 



Definitions of ADV fields; 

BtOf (- Bit offset) : For an array of bit 
strings with the UNALIGNED attribute, 
this is the bit offset from the byte 
address of the virtual origin. 



Virtual origin: The byte address of the 
array element whose subscript values 
are all zero, i.e. ,X(0, . . . ,0) ;this 
element need not be an actual member of 
the array, in which case the virtual 
origin will address a location in 
storage outside the actual bounds of 
the array. 



Multiplier: These are fullword binary 
integers which, in the standard ADV 
algorithm, effect dimensional 
incrementation or decrementation to 
locate an element. Bit multipliers are 
used for fixed- length bit string 
arrays; byte multipliers are used for 
everything else. 



Upper Bound: Half word binary integer, 

specifying the maximum value permitted 
for a subscript in the ith dimension. 
This value may be negative. 

Lower Bound: Half word binary integer, 

specifying the minimum value permitted 
for a subscript in the ith dimension. 
The value may be negative. 

ADV Algorithm: Given subscript values for 
an n-dimensional array, the address of 
any element is computed as: 



Address = origin + J* 



S^M, 



where S^ = value of the ith subscript 
M^= value of the ith multiplier 

For an array of bit strings with the 
UNALIGNED attribute, the origin is a 
bit address formed by concatenating the 
virual origin and the bit offset. For 
all other arrays, the origin is the 
virtual origin. 
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DATA ELEMENT DESCRIPTOR (DED) 



"T T 

15 16 and onwards 



| | Bytes 

| |. 1 T T 

Data type | Representation | 1 | 2 | 3 | U 

| Fixed-point I I I I 

j Floating-point | Flags j p j q j 

Arithmetic! Packed decimal I j j j 

j Numeric field j j Flags | p j q j w | 1 j Picture specn 

| Unpictured | Flags | - | - | - | - | 

j Pictured j Flags | 1 | Picture specification 

l A X J X 

Figure 51. Format of the Data Element Descriptor (DED) 






Code 



Bit 







Unaligned 



Aligned 



Non- 
sterling 



Fixed 



Varying 






Picture! Bit 



No 

Picture! Character] 



Numeric) 

field Decimal | Fixed 




Short 

j = 1 j I * I Sterling! Long j Coded j Binary | Float | Complex! 

* These bits are used by the compiler, but, when a DED is passed to a library 
module, they are always set to zero. 

NOTE: the hexadecimal •10' superimposed on the DED Flag byte indicates the presence of a 
halfword fixed point binary variable. Bit 3 is set to 1 and bit 6 is set to 0. . 

Figure 52. Format of the DED Flag Byte 



Data element descriptors (DEDs) contain 
information derived from explicit or 
implicit declarations of variables of type 
arithmetic and string. There are four DED 
formats; they are shown in Figure 51. 

Definitions of DED fields: 

Flags: An eight- bit encoded form of 

declared information (Figure 52). Those 
flags which are specified as zero must be 
set to zero. 

p byte: p is the declared or default 
precision of the data item. 

g byte: g is the declared or default scale 
factor of the data item, in excess- 128 
notation (i.e., if the implied fractional 
point is between the last and the 
next -to-last digit, q will have the value 
129). 



For numeric fields, q is the resultant 
scale factor derived from the apparent 
precision as specified in the picture, 
i.e., the number of digit positions after 
a V picture item as modified by an F 
(scale factor) item. 

For fixed decimal pictures, any explicit 
scaling of the form F(±I) is combined 
with the implied scale, as described 
above, and reflected in the DED. The 
F(±I) is then no longer required and is 
removed from the picture. 

w byte: w specifies the number of storage 
units allocated for a numeric field. 

1 byte(s): 1 specifies the number of bytes 
allocated for the picture associated with 
a numeric field. If the data item is 
string, 1 occupies two bytes; if 
arithmetic, one byte. 



Appendix H: Data Element Descriptor (DEDK 185 



Picture specification: This field 

contains the picture declared for the 
data item. If the data item is string, 
the picture may occupy 1 through 32,767 
bytes; if arithmetic, 1 through 255 
bytes. If the original picture 
specification contained replication 
factors, it will have been expanded in 
full. 
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DOPE VECTOR DESCRIPTOR (DVD) 



This provides a key for scanning the 
standard array, string and structure dope 
vectors. It consists of one entry for each 
major structure, minor structure and base 
element in the original declaration. Each 
entry consists of one word and can have one 
of two formats: 



1. Structure: 



12 7 8 15 

r — t — r t 1 

|F1|F2| L | N | 

L X X i. J 

16 31 

r 1 

| Offset j 

i j 



F1 

F2 

L = 

N 

Offset = 



= 
= 



Structure 



Level of structure 

Dimensionality, including 
inherited dimensions 

Offset of containing 

structure from start of 

DVD 

- 1 for a major structure 



2. Base element: 

12 7 8 9 10 15 

r T T T T T 1 

|F1|F2| L | F5 | F6 | N | 

l X X X J. X J 

16 17 18 23 2U 31 

r T T T T T 1 

|F3|F4| A | | | D | 

I A__ X J X X J 

F1 = 1 Base element 

F2 = Not end of structure 
= 1 End of structure 

L = Level of element 

F5 - 1 Area variable 

- Not area variable 

F6 = 1 Event variable 

= Not event variable 

N = Dimensionality 

F3 = Not an aligned bit string 
= 1 Aligned bit string 

FU = Not a varying string 
= 1 Varying string 

A = Alignment in bits (0 to 63) 

D = Length, if not a string, in 
bits 
= if a string, in which case 
the length is in the dope 
vector 
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FORMAT ELEMENT DESCRIPTOR (FED) 



This control block contains information 
derived from a format element within a 
format list specification for edit-directed 
I/O. There are five forms of the FED: 

1. Format item E: 



| %» T * T s~i 

l J A J 



w = width of data field in characters 

d = number of digits following decimal 
point 

s = number of significant digits to be 
placed in data field (ignored for 
input) 

2. Format item F: 



I T T 1 

I w | d | p | 
i j x I 

w and d: as for E format 

p = scale factor in excess- 12 8 
notation 



Format items A, B, Xi 

1 2 

r 1 

I w | 
i j 

w = as for E format 
Format item P: 



There are two forms of the FED for the 
P format items, these being identical 
to the DEDs for numeric fields and 
pictured character strings. 



Printing format items PAGE, SKIP, LINE, 
COLUMN: 

The FEDs for SKIP, LINE and COLUMN are 
half word binary integers. PAGE does 
not have an FED. 
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LIBRARY COMMUNICATION AREA (LCA) 




M 
8 

10 

14 

18 
20 
29 

2A 
2B 
2C 

34 
38 

CE 

D2 

D6 
DE 
E6 
EA 

F2 
F6 





| Symbolic 


Length 




j name 


(bytes) 


Function 


L J 


L_ J. 


r 1 


r — t 




j W6R1 


4 


2nd XCTL address for communication in arithmetic 
conversion package. 


| WBR2 


U 


3rd XCTL address for communication in arithmetic 
conversion package. 


| WRCD 


8 


A (Target) ,A(DED) : Implicit parameters for final 
conversion in arithmetic scheme. Stored by 
arithmetic director. 


| WFED 


4 


A (Source FED): Implicit parameter for F or E 
format input conversion. 


| WSCF 


4 


Scale factor for library decimal intermediate 
form. 


| WSDV 


8 


Input/output field dope vector. 


| WINT 


9 


Library intermediate form storage area. 


| WSWA 


1 


Eight 1-bit switches: Intermodular 
communication. 


| WSWB 


1 


Eight 1-bit switches: General purpose switches. 


j WSWC 


1 


Eight 1-bit switches: Not used across calls. 


| WOFD 


8 


Dope vector for ONSOURCE or ONKEY built-in 
functions. 


| WOCH 


4 


A (Error character): ONCHAR built-in function. 


j WFCS 


150 


Character string (in required format) used by 
list-directed and data-directed output. 


| WCFD 


4 


Library intermediate FED: String/arithmetic 
conversion. 


| WFDT 


4 


A (Target FED): Implicit parameter for F or E 
format output conversion. 


| WODF 


8 


SDV for DAT AFIELD in error. 


j WCNV 


8 


Library GO TO control block. 


| WFIL 


4 


A(DCLCB) for ONFILE. 


j WOKY 


8 


SDV(Null string); requested when ONKEY built-in 
function used out of context. 


| WEVT 


4 


A5( event variable). 


| WREA 


4 


Return address for AREA on-unit. 



Alternative entries: 

r t r 1 

38 | WFC1 | 40 | Workspace for interleaved array indexer. | 

60 j WONC j 40 j Error code; storage area for contents of j 

j j j floating-point registers in error-handling | 

j | j subroutines. j 

t x x .j 

r t t 1 

38 | WCNP | 4 | Implicit parameter: A (Constant descriptor). | 
3C | WCN1 j 8 | A(Start of constant), A(End of constant). j 
44 j WCN2 | 8 j A (Start of constant), A(End of constant). j 

l X- l J 

Figure 53. Library Communication Area (LCA) 

The library communication area (LCA) is part of library workspace 
(LwS), the format of which is given in Figure 54. The use of LWS and 
LCA is described in 'Communication Conventions' in Chapter 2. 
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LIBRARY WORKSPACE (LWS) 



7 8 

IHEQLSA > r T — 

| Flags j 
j._. 



31 



a 

8 

c 

48 



IHEQLWO-- 



50 



IHEQLW1 > 

E8 



IHEQLW2 > 

180 



IHEQLW3 > 

218 



IHEQLWU > 

2B0 



IHEQLWE > 

348 



Length 



Chain- back address 



Chain- forward address 
Register save area 
(8 bytes unused) 



Workspace level 



Workspace level 1 



Workspace level 2 



Workspace level 3 



Workspace level 4 



Workspace level E 



1 



•H 



H 



•H 



IHEQLCA > 

3E0 



Library communication area (LCA) 

IHEQLWF >«• J 

Figure 5<t. Standard Format of Library Workspace (LWS) 

The use of Library Workspace (LWS) is described in Chapter 2. 
The format of the LCA is given in Figure 53 and that of the SSA 
in Figure 55. 
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STANDARD SAVE AREA (SSA) 



Offset 



General Register 



alue 


Symbolic 
Name 


Number 


Symbolic 
Name 





OFCD 


- 


- 


4 
8 
C 


OFDR 


13 


DR 


OFLR 


14 


LR,RY 


10 


OFBR 


15 


BR,RZ 


14 


OFR0 





R0 


18 


OFRA 


1 


R1,RA 


1C 


OFRB 


2 


RB 


20 


OFRC 


3 


RC 


24 


OFRD 


4 


RD 


28 


OFRE 


5 


RE 


2C 


OFRF 


6 


RF 


30 


OFRG 


7 


RG 


34 


OFRH 


8 


RH 


38 


OFRI 


9 


RI 


3C 


OFRJ 


10 


RJ 


40 


OFWR 


11 


RX,WR 


44 


OFPR 


12 


PR 



7 8 



Standard Save Area 



Usag e 



31 



j Flags J 

L X_ 




Length 


j Chain-back address 


j Chain- forward address 






j Contents 


of 


register 




j Contents 


of 


register 


j Contents 


of 


register 


| Contents 


of 


register 


j Contents 


of 


register 


| Contents 


of 


register 


j Contents 


of 


register 


j Contents 


of 


register 


j Contents 


of 


register 


| Contents 


of 


register 




1 Pseudo-register pointer 



Figure 55. Format of the Standard Save Area <SSA) 



Flags: One-byte code, employed by PL/I 

housekeeping procedures to specify the 
nature of the storage area in which the 
SSA resides. (See Figure 56.) 



Length: Three- byte binary integer 

specifying the total length of the 
storage area in which the SSA resides; 
used by PL/I housekeeping to free 
dynamic storage areas. (See • PL/I 
Object Program Management'.) When 
OPT=01. Default is used, bit 1 of these 
three bytes is used as a flag. 

Chain- back Address: Address of the SSA 
originally provided for a module that 
now calls another module. 



Chain-forward Address: Address of the SSA 
acquired by a called module. This 
field is not set for any PL/I Library 
module, since intermodule trace is not 
supported within the library. 



Return address of the calling module: 

Contents of register LR on entry to the 
called module, set by the calling 
module to the address of the point of 
return. All PL/I Library modules 
return using register LR. 



Entry Point of the called module: Contents 
of register BR on entry to the called 
module. 
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RO to PR: Contents of the specified 
registers on entry to the called 
module. PL/I Library modules save all 
registers LR through WR in order to 
meet the requirements of a GO TO 
statement in an on- unit. (See Chapter 
*».) The register PR field is set by 
the subroutine in IHESA that 
initializes the main procedure; it 
remains unchanged throughout the task. 



BitK 

+ 



+ 

1 



No dummy ON field 
for STRINGRANGE 






Meaning 

— = ° _ I— \T 
Always = 1 



No statement num- 
ber field in DSA 



Procedure DSA 






No dummy ON field 
for SUBSCRIPTRANGE 



Non- recursive DSA, 
without display 
update field 

No ON fields 



Statement number 
field in DSA 



-H 



STRINGRANGE field 
created as for 
other ON conditions 

Begin block DSA 



SUBSCRIPTRANGE 
field created as 
for other ON con- 
ditions 



■H 



Recursive DSA, 
with display up- 
date field 

ON fields 



No dummy ON field 
for SIZE 



SIZE field created 
as for other ON 
conditions 

Figure 56. Format of the SSA Flag Byte 
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STRING ARRAY DOPE VECTOR (SADV) 



15 16 



31 



ADV 



* r ^ 

| Maximum length | Current length/ | 

Figure 57. Format of the Primary String 
Array Dope vector (SADV) 

This control block contains information 
required to derive, directly or indirectly 
(through a secondary array of SDV entries), 
the address of elemental strings. The SADV 
is identical to the basic ADV, with the 
addition of a fullword which describes the 
string length. 

Fixed-length strings require only a 
primary dope vector. The two length fields 



are set to the same value, which is the 
declared length of the strings. 



VARYING strings require, in addition to 
the primary dope vector, a secondary dope 
vector. This consists of SDV entries for 
each elemental string within the array. 
The secondary dope vector is addressed via 
the primary dope vector by the standard ADV 
algorithm; having located the relevant SDV 
the actual string data is directly 
addressable. The maximum- length field 
appended to the ADV is set to the declared 
maximum length of each array element. The 
current- length field is set to zero. 



The multipliers of the ADV for a 
fixed-length string apply to the actual 
string data. Those of the ADV for a 
variable- length string apply to the 
secondary dope vector of SDV entries. 
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STRING DOPE VECTOR (SDV) 



2 3 7 8 15 16 31 

r t t 1 

|BtOf| | Byte address of string | 

i. — x x , ^ 

| Maximum length | Current length | 
l x j 

Figure 58. Format of the String Dope 
Vector (SDV) 

A string dope vector (SDV) is an 8-byte 
word- aligned block that specifies storage 
requirements for string data. 

Definition of SDV fields; 

BtOf (Bit offset): If the string is a bit 
string, positions to 2 of the SDV 
specify the offset of the first bit of 
the string within the addressed byte. 
The bit offset is only applicable to 
bit strings which form part of a data 
aggregate, and then only if that 
aggregate has the UNALIGNED attribute. 

Byte address of string: For both character 
and bit strings, this three- byte field 



specifies the address of the initial 
byte of the string. 



Maximum length: Half word binary integer 
which specifies the number of storage 
units allocated for the string; byte 
count if character string, bit count if 
bit string. This value does not vary 
for a particular generation of its 
associated string. 



Current length: Half word binary integer 
which specifies the number of storage 
units, within the maximum length, 
currently occupied by the string; only 
applicable to strings with the VARYING 
attribute. 

The two length fields exist to 
accommodate strings with the VARYING 
attribute; in the instance of a 
fixed-length string, the two fields contain 
identical values. Both fields may contain 
a maximum value of 32,767. 
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STRUCTURE DOPE VECTOR 



This control block contains information 
required to derive, directly or indirectly, 
the address of all elements of the 
struct tare. 

The format of a structure dope vector is 
determined as follows. The dimensions 
which have been applied to the major 
structure or to minor structures are 
inherited by the contained structure base 
elements; undimensioned non-string base 
elements are assigned a dope vector 
consisting only! of a single-word address 
field. The structure dope vector is then 
derived by concatenating the dope vectors 



which the base elements would have if they 
were not part of a structure, in the order 
in which the elements appear in the 
structure. 



The following structure would result in 
a dope vector of the form shown below in 
Figure 58.1. 

1A, 2B(10), 3C(10) CHARC6), 

3D BIT (10) VARYING, 
2E, 3F FLOAT (5), 
3G(10) FIXED, 
3H CHAR (3) ; 



31 



|. 



C'sj Virtual origin 
Multiplier! 



Multipliers 



Upper bounds | Lower bounds. 
Upper bounda | Lower bound a 
Maximum length j Current length 
D's Virtual origin 
Multiplier 



f 

Upper bound | Lower bound 

Maximum length j 
F's Address 

j. 



> Dope 
Vector 



Upper bound 



G»s Virtual origin 
Multiplier 

I Lower bound 



H*s Address 



Maximum length 



j Current length 

.x 



E's 

> Dope 
Vector 



A's 
> Dope 
vector 



• Figure 58.1 Format of the Structure Dope Vector (8DV) 
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SYMBOL TABLE (SYMTAB) 



7 8 



Length j 
.-j 



15 16 
Chain-forward address 

Identifier 



31 



Flags; 



^ , 

Flags j 



A(DED) 
Field A 



Field B | 

L A 

Figure 59. Format of the Symbol Table 
(SYMTAB) 



1 
^ 


Bit 



i 


1=1 


i 


2=1 


i 


3 


i 


4 


1 
i 


Bits 


i 
^ 


5 6 7 



i 


1 



10 



(Reserved) 

ON CHECK for the variable 

ON CHECK for label variable 

(Reserved) 

(Reserved) 



Variable is STATIC 

Non- structured AUTOMATIC or 

CONTROLLED 

Structured AUTOMATIC or 

CONTROLLED 



The symbol table consists of one or more 
entries which define the attributes , 
identifier , and storage location of 
variables which appear in the data list for 
data-directed I/O. Each SYMTAB entry 
contains the address of the next entry or a 
stopper. 



Definition of SYMTAB fields: 

Chain- forward address: The address of the 
next entry in the symbol table; all 
symbols (identifiers) known within a 
given block are chained together. The 
last entry in the chain is signaled by 
a zero chain- forward address. (The 
symbol table of a contained block must 
include the symbol table of the 
containing block; hence the 
chain-forward address of the last entry 
for variables declared in a contained 
block is that of the first entry in the 
symbol table of the containing block.) 

Length: Number of characters comprising the 
identifier. Maximum length is 255 
characters. 

Identifier: The name declared for a 

variable. If the variable is known by 
a qualified name, the identifier 
includes separating periods. 

D (= Dimensionality) : The number of 
dimensions declared for an array 
variable; D - for scalar variables. 

A (DED) : Address of the data element 
descriptor associated with the 
variable. 



Field A : 

If STATIC: Address of data item or its 
dope vector. 

If AUTOMATIC (non-structured) : Offset of 
data item or its dope vector 
within DSA. (See note.) 



If AUTOMATIC (structured) : Offset of dope 
vector for data item (within a 
structure dope vector) , 
relative to origin of DSA. 
(See note.) 



If CONTROLLED (non-structured) : Offset to 
data item or its dope vector. 

If CONTROLLED ( structured ) : As for 

AUTOMATIC (structured), but 
offset is relative to origin 
of structure dope vector. 



Field B: 

If STATIC: Not used. 

If AUTOMATIC: Offset of display within 
PRV. 

If CONTROLLED: Offset of the anchor word 
(pseudo-register) of the 
controlled variable. 

Note: See Chapter it for description of 

storage class implementation and for 
definition of DSA. 
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APPENDIX I: INPUT/OUTPUT CONTROL BLOCKS 



This appendix gives the formats of the control blocks used by the PL/I Library I/O 
interface modules, including those blocks generated by the compiler. The functions of 
the blocks and the way in which they are used by the library are described in Chapter 3. 
In the diagrams, all offsets are in hexadecimal. 

The appendix includes an example of the chaining of I/O control blocks. 
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DECLARE CONTROL BLOCK (DCLCB) 



7 8 





1 

8 

C 

10 

1U 

18 



15 16 



23 24 

DCLA 

DLRL 



31 



DPRO | 
DBLK | 
DCLD j DBNO | DCLB | DCLC | 
DXAL jNCP Value | Reserved | 
(Reserved) 



H 



(Reserved) 



1 



T* 

DFLN | 



■H 



DFIL 



L J 

Figure 60. Format of the Declare Control 
Block (DCLCB) 



DPRO: Halfword binary integer (set by the 
linkage editor) specifying the offset, 
within the pseudo-register vector 
(PRV) , of the pseu do- register 
associated with the declared file. 



Byte 2 



0001 xxxx 
0010 xxxx 



Access 

SEQUENTIAL 
DIRECT 



(These are used for record-oriented I/O 
only. ) 



xxxx 0001 
xxxx 0010 
xxxx 0100 
xxxx 1000 



Mode 

INPUT 
OUTPUT 
UPDATE 
BACKWARDS 



(Stream-oriented I/O uses INPUT and 
OUTPUT only,) 



DBLK: Halfword binary integer specifying 
the length, in bytes, of the blocks 
within the data set: 

F-format records: block length 

specified for data set (constant 
for all blocks except possibly the 
last one) . 

U-, V-, VS- or VBS-format records: 
maximum length of any block in 
data set. 



DCLA: Four four-bit codes specifying 

the file type, organization, access and 
mode: 



TP: maximum message length 



Byte 1 



0001 xxxx 
0010 xxxx 



xxxx 0000 
xxxx 0001 
xxxx 0010 
xxxx 0011 
xxxx 0100 
xxxx 0101 



Type 

STREAM 
RECORD 

Organization 

CONSECUTIVE 
INDEXED 
REGIONAL (1) 
REGIONAL (2) 
REGIONAL (3) 
TELEPROCESSING 



(Stream-oriented I/O is supported only 
for data sets of CONSECUTIVE 
organization. ) 



DLRL: Halfword binary integer specifying 
the length, in bytes, of the records 
within the data set. Two or more 
records may be grouped (blocked) to 
form one physical block. 



F-format records: record length 

specified for data set (constant 
for all records) . 

V-, VS- or VBS-format records: maximum 
length of any record in the data 
set. 

U-format records: this specification is 
not permitted; the block size 
defines the record length. 
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DCLD: One byte containing 
ENVIRONMENT options: 



DCLC: Eight- bit code which specifies the 
format of records within the data set: 



Bit 



Option 



Bits 



Code 



Format 






LEAVE 


1 


COBOL file 


2 


CTLASA 


3 


CTL360 


a 


INDEX AREA 


5 


NOWRITE 


6 


REWIND 


7 


GENKEY 






and 


1 


01 


V 





and 


1 


10 


F 





and 


1 


11 


U 




2 




- 


(Reserved) 




3 




1 


Blocked 




4 




1 


VS/VBS 




5 




1 


PRINT/G 




6 




1 


R 




7 




- 


(Reserved) 



DBNO: One-byte binary integer specifying 
the number of buffers to be allocated 
to the file when it is opened, as 
specified by the BUFFERS option. 

DCLB: One byte containing attribute 
codes : 



it 


Attribute 





KEYED 


1 


EXCLUSIVE 


2 


BUFFERED 


3 


UNBUFFERED 


a 


TRANSIENT 


5 


(Reserved) 


6 


(Reserved) 


7 


(Reserved) 



DXAL: Halfword binary integer specifying 
the count in the INDEX AREA area 
environment option. 

DFLN: One-byte binary integer specifying 
the length (minus one) in bytes of the 
file name in the following field. 

DFIL: Character string, up to 31 bytes 

long, specifying the name of the file. 
If there is no TITLE option in the OPEN 
statement, the first eight characters 
of this name are used as the name of 
the DD statement associated with the 
file during program execution. (The 
compiler will have padded the name with 
blanks to extend it to at least eight 
characters in length.) 
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EVENT VARIABLE 



7 8 



15 16 



31 





4 

8 

C 

10 

14 

18 



EVF1 j EVEC 

EVF2 I EVIO 






EVCF 
EVCB 



EVST 



Reserved 



EVFF 
EVFB 



1C | EVPR 

Figure 61. Format of the Event Variable 



In a multitasking environment, event 
variables are placed in two chains: 



1. The file chain, which is anchored in 
the TEVT field of the FCB and includes 
all active event variables related to 
a file and for which there is no 
corresponding IOCB. This chain 
enables all associated event variables 
that are not being waited on to be set 
inactive, complete, and abnormal when 
a file is closed. 



2. The task chain, which is anchored in 
the pseudo- register IHEQEVT, and 
includes all active I/O event 
variables associated with the task. 
This chain facilitates the setting of 
those event variables that are not 
being waited on inactive, complete, 
and abnormal on termination of the 
task. 



An example of the chaining of event 
variables is given at the end of this 
appendix. 



EVF1: 8-bit code containing implementation 
flags: 



Flags 



Code 



Name 



Active event variable 


1000 


0000 


EMAC 


I/O associations 


0100 


0000 


EMIO 


No WAIT required 


0010 


0000 


EMNW 


FCB address contained 








in the first word 


0001 


0000 


EMFC 


This event variable 








is to be checked 


0000 


1000 


EMCH 


DISPLAY event variable 


0000 


0100 


ENDS 


IGNORE option with 








this event 


0000 


0010 


EMIG 



EVEC: Contains the address of the DECB 
associated with the event, or the 
address of the FCB when no IOCB was 
obtained, e.g., when READ IGNORE (0) 
is executed. 



EVF2. PL/I ECB flag byte: 




Flaqs Code 


Name 


Wait 1000 0000 


EMWB 


Complete 0100 0000 


EMCP 


EVIO: Not used. 




EVCF: Event variable chain- forward poi 


nter 



(task) . 

EVCB: Event variable chain- back pointer 
(task). 

EVST: Status field: 

Normal status value: All zeros. 
Abnormal status value: Low-order bit 

is 1, remainder is zero (unless 

set otherwise by STATUS 

pseudo-variable) . 

EVFF: Event variable chain- forward pointer 
(file). 

EVFB: Event variable chain- back pointer 
(file). 

EVPR: Address of the PRV of the task in 
which the associated I/O event was 
initiated. 
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EXCLUSIVE BLOCK 





4 

8 

C 

10 

14 

18 

20 
24 



7 8 






K 



15 16 
XCFF 



31 



XCBF 
XCFT 



XCBT 
XPRV 



XFL1 | (Reserved) | 
XQNM 



XSTC 



H 

4 

— ^ 



K- 



XLRN 



XKYI/XREG 






XKYR 



A 
^ I 



XRNM 



L J 

Figure 62. Format of Exclusive Block 

Exclusive blocks are placed in -two 
chains : 

1. The task chain, which is anchored in 
the pseudo- register IHEQXLV, and 
enables all records locked in a task 
to be unlocked when the task is 
terminated. 

2. The file chain, which is anchored in 
the TXLV field of the FCB, and 
facilitates the freeing of all 
exclusive blocks related to the file 
when it is closed, and facilitates a 
check on whether a record is already 
locked. 

An example of the chaining of exclusive 
blocks is given at the end of this 
appendix. 



XCFF: Chain-forward pointer (file). 



XCBF: Chain-back pointer (file) 



XCFT: Chain-forward pointer (task). 

XCBT: Chain-back pointer (task). 

XPRV: Address of the PRV for the task in 
which the exclusive block was 
created. 

XFL1: Flags: XLOK: Code 1000 0000 indicates 
that the record associated with the 
exclusive block is locked owing to a 
READ operation or an incomplete 
REWRITE or DELETE operation. 

XSTC: Lock statement count: the number of 
incomplete I/O operations that 
currently refer to the exclusive 
block. 

XQNM: Eight-byte qname used in the ENQ and 
DEQ macro instructions. The first 
word contains the address of the FCB, 
right-aligned, and the second 
contains zero. 

XRNM: The rname used in the ENQ and DEQ 
macro instructions: 

XLRN: One byte containing the length 
of the rname. 

XKYI/XREG: 

XKYI: INDEXED files (unblocked 

records) : Key of record 

being locked. 

INDEXED files (blocked 

records) : A (FCB). 
XREG: REGIONAL files: Region 

number of the record 

being locked. 

XKYR: REGI0NAL(2) and (3) files: The 
recorded key of the record 
being locked. 
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FILE CONTROL BLOCK (FCB) 



7 8 



-8 

-4 



4 

8 

C 

10 

14 

18 

1C 

20 

24 

28 

2C 

30 



15 16 
TVAL 



23 24 



31 



TRES 



TFLX | TDCB 
TTYP | TACM 
TFLA J TFLB | TLEN 
TFIO | TDCL 
TCBA 
TREM | TMAX 
TREC 
TCNT 
TPGZ | TLNZ 
TLNN | TFLC | TFLD 

l . T — . x 1 .j 

TFLE | TFOP 
TFLF | TTAB 



DCB 



Figure 63. FCB for Stream-Oriented I/O 

TVAL: Word containing bits indicating 
which statements are valid for this 
file 

TRES: Reserved 

TFLX: Eight- bit code specifying error and 
exceptional conditions : 



Conditions 

EOF on data set 
Error on output 
Error on input 
Error on data field 
Do not raise 

TRANSMIT 
List terminator 
ENDPAGE raised 



Code 



Name 



1000 0000 TMEF 

0100 0000 TMOE 

0010 0000 TMIE 

0001 0000 TMIT 

0000 1000 TMNX 

0000 0010 TMLC 

0000 0001 TMEP 



-8 
-4 

4 
8 
C 
10 
14 
18 
1C 
20 
24 
28 
2C 
30 
34 
38 
3C 
40 
44 



7 8 15 16 23 24 

TVAL 

TRES 

TFLX | TDCB 

TTYP | TACM 

TFLA | TFLB | TLEN 
j. + X 

TFIO | TDCL 

X 



»■ — 









TLAB/TCBA 
TPKA/TSWA 
TBBZ/TREL 
TADC 



31 

T 

-H 

-H 

— I 

— I 

-H 
_l 

— I 



TLRL 






TLRR/TAID 

| TFLC | 



TFLD 







TFLE | TFOP 
x T 

TFLF j TFMP j 


(Reserved) 


TEVT 




Zero 




TXLV* 




Zero* 





H 



TXLZ* 



j. 



h 
h 

■H 
H 
■H 
■H 
-H 
■H 
■H 

-H 
-H 



DCB 



* These fields are omitted in 

non-multitasking environment: DCB 
commences at byte 38. 

• Figure 64. FCB for Record-Oriented I/O 



TDCB: Address of the DCB part of the FCB. 



TTYP: Eight-bit code specifying I/O .type: 
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Type 



Code 



Name 



STREAM I/O 


xxxx 


0000 


TMDS 


RECORD I/O 


xxxx 


0001 


TMRC 


STRING I/O 


xxxx 


0010 


TMST 


Temporary flags. 


1000 


xxxx 


TMT1 


valid for single 


0100 


xxxx 


TMT2 


I/O call only 


0010 


xxxx 


TMT3 




0001 


xxxx 


TMT4 



TCBA/TLAB: 



TACM: Address of I/O transmit module, 

which interfaces with data management 
access methods. The names of all such 
library modules are IHEIT*, where * is 
a letter identifying the module. 

TFLA: Two four- bit codes specifying the 
record format and the current file 
mode: 



Format 



Code 



Name 



V (variable) 


0001 


xxxx 


TMVB 


F (fixed) 


0010 


xxxx 


TMFX 


U (undefined) 


0100 


xxxx 


TMUN 


ASA control/print 








file 


lxxx 


xxxx 


TMAS 


Mode 


Code 


Name 


INPUT 


xxxx 


0001 


TMIN 


OUTPUT 


xxxx 


0010 


TMOP 


UPDATE 


xxxx 


0100 


TMUP 


BACKWARDS 


xxxx 


1000 


TMBK 



TFLB: Eight-bit code specifying the file 
attributes: 



Attribute 

EXCLUSIVE 
UNBUFFERED 
Hidden buffers 
SYSPRINT file 
Hidden buffer may 

be required 
KEYED 
DIRECT 



Code 



Name 



lxxx xxxx TMEX 
xlxx xxxx TMBU 
xxlx xxxx TMHB 
xxxl xxxx TMPT 

xxxx xlxx TMHQ 

XXXX XXlx TMKD 

xxxx xxxl TMDR 



TLEN: Halfword binary integer, specifying 
the length, in bytes, of the FCB. 

TFIO: Eight-bit code specifying the type 
of I/O operation: 



Operation 



Code 



Name 



PUT 


1000 


0000 


TMPW 


GET 


0100 


0000 


TMGR 


EVENT option 








with IGNORE option 


0000 


0010 


TMEI 


COPY option 


0000 


0001 


TMCY 



TDCL: Address of the DCLCB defining the 
file. 



STREAM: TCBA: Address of next available 
byte in a buffer. 



RECORD: TLAB: 

Sequential: Address of last 

IOCB obtained. 
Direct: Address of first IOCB 

in chain. 
TCBA: 
Sequential: Address of last 

record located. 

TREM/TMAX/TPKA : 

STREAM: TREM: Number of bytes remaining 
in current record. This value 
is equal to TLNZ when the 
record is initialized for 
output. 

TMAX: Halfword binary integer 
specifying the number of bytes 
in a record: 



Input : 
read. 



the number of bytes 



RECORD i 



Output : the number of bytes 
initially available. 

For V format records, this 
number includes the four-byte 
record control field; for all 
record formats, it includes the 
ASA control byte (if present). 

TPKA: Address of previous key. 
(Used for SEQUENTIAL access to 
REGIONAL data sets, LOCATE 
creation of INDEXED data sets, 
and padding key for SEQUENTIAL 
INDEXED data sets.) 
TSWA: Address of data in dummy 
buffer got at OPEN time 



TREC/TBBZ/TREL : 

STREAM: TREC: Address of buffer 

workspace (paper- tape input, 
U- format output) . 



RECORD : 



TBBZ: Length of IOCB. The 

first byte contains the subpool 

number. 

TREL: Relative record count. 

(Used only for SEQUENTIAL 

access to REGIONAL data sets.) 



TCNT/TADC: 



STREAM: TCNT: . Full word binary integer 

specifying the number of scalar 
items transmitted during the 
most recent I/O operation (GET 
or PUT) on the file 
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RECORD: TADC: Address of the adcon 
list. 

TPGZ/TLNZ/TLRR/TAID : 

STREAM: TPGZ: Half word binary integer 
specifying the maximum number 
of lines per page. This field 
is only used for PRINT files. 
A default value of 60 lines is 
assumed if: 



the OPEN statement that 
opens the file does not 
include the PAGES I ZE 
option, or 

an implicit open occurs. 



TLNZ: Half word binary integer 
specifying the maximum number 
of characters per line. A 
default line size is obtained 
from the record length 
specified in the ENVIRONMENT 
attribute if: 

1- the OPEN statement that 
opens the file does not 
include the LINESIZE 
option, or 

2. an implicit open occurs. 



If the ENVIRONMENT attribute is 
not specified, the record 
length used is that specified 
in the associated DD statement. 



If none of these specifies a 
record size, and if the file is 
a print file, a default length 
of 120 characters per line is 
assumed. 

The TLNZ value includes all 
characters available within a 
line. 

RECORD: TLRR: Address of IOCB of last 
complete READ operation. This 
is reguired whenever the EVENT 
option is used; it provides a 
means of identifying the last 
complete READ operation when a 
REWRITE is executed. In the 
case of spanned records this 
field holds the length of the 
previously read record if the 
previous operation was a READ 
SET. 

TAID: Address of dummy work 
area for terminal 
identification. 



TLNN/TLRL: 



STREAM: TLNN: Half word binary integer 
specifying the current line 
number. 



RECORD: TLRL: Maximum logical record 
length for the file. 



TFLC: Two 4-bit codes giving: 

1. Type of device. 

2. Further file history. 



Device 

Paper tape 

Printer 

Previous operation 

was READ with SET 

option 
Attempt to close in 

wrong task 
OPEN or CLOSE 

in progress 



Code 



Name 



1000 0000 TMPA 
0100 0000 TMPR 



0000 1000 TMPS 
0000 0100 TMDT 
0000 0010 TMOC 



TFLD: Eight-bit code specifying the 

organization of the data set associated 
with the file: 



Organization 



Code 



Name 



CONSECUTIVE X • • 


TMCN 


INDEXED X'04* 


TMIX 


REGIONAL (1) X^B* 


TMR1 


REGIONAL (2) X'OC 


TMR2 


REGIONAL (3) X'10' 


TMR3 


TELEPROCESSING X'lU* 


TMTP 


!: Eight-bit code specifying 


the 


history of the file: 




History Code 


Name 



Preceding operation 

a READ 
IGNORE in progress 
CLOSE in progress 
End of the extent 

reached by the 

last operation 
Preceding operation 

a REWRITE 
Preceding operation 

a LOCATE 
I/O condition on 

CLOSE 
Implicit CLOSE 



1000 0000 TMRP 
0100 0000 TMIG 
0010 0000 TMCL 



0001 0000 TMET 

0000 1000 TMWP 

0000 0100 TMLT 

0000 0010 TMCC 

0000 0001 TMCT 



TFOP: Address of the prior PCB opened in 
the current task, or zero (if FCB is 
the first FCB opened) . 
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TFLF: Eight-bit code specifying the 
load module code (used by IHECLS, 
IHECLT and IHECTT to specify module 
names in the DELETE macro) : 



STREAM: 






Miscellaneous 


Code 


Name 


TAB table exists 


0000 0001 


TMTB 


RECORD: 






Module Code 


Code 


Name 


QSAM 


X'OO 1 


TMQS 


BDAM 


X'OU' 


TMBD 


QISAM 


X'08 f 


TMQI 


BISAM 


X'OC* 


TMBI 


BSAM 


X'10' 


TMBS 


BSAM load mode 


X'14 f 


TMBL 


QTAM 


X'18' 


TMQT 


Tab control table 




exists 


X'OV 


TMTB 


TTAB: Address of TAB 


control table 


(PRINT 


files only) . 







TFMP: RECORD I/O only. This flag is used 
by exclusive files to act as a lockout 



flag when updating the chains of IOCBs 
and exclusive blocks. A TS loop is 
performed on this byte until it is 
freed. When the chaining operation is 
complete, the byte is set to zero. 

TEVT: Pointer to chain of active I/O event 
variables associated with the file, but 
for which there is no corresponding 
IOCB: enables the event variables to be 
set complete, inactive, and abnormal 
when the file is closed. 

TXLV: Pointer to chain of exclusive blocks 
associated with locked records of the 
file: enables locked records to be 
unlocked when the file is closed. 
(Used only in a multitasking 
environment. ) 

TXLZ: Length of exclusive block: the first 
byte contains X'01'( the number of the 
subpool in which storage for the block 
is allocated) . 

DCB: This field, variable in length and 
format, is the data control block 
defined by data management for the 
various access methods. 
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INPUT/OUTPUT CONTROL BLOCK (IOCB) 



7 8 



T 

BACT j 

BERR I 



15 16 

BPIO 
BNIO 
BFCB 



31 



1 

-H 



o 
4 

8 
C 

14 
18 
1C 
20 
24 
28 
2C 
30 
34 
38 
3C 
40 
44 
48 
4C 
50 



|. J. 

BREQ 

BERC/BEFC/BXTC/BKYC | 

i- 









BRCC 



BRVS 
BEVN 



BDF1/BBF1 



BDF2/BBF2 



BDF 3/ (Reserved) 



■H 



BDF4/BBF3 



BDF5/BBF3 (contd. ) 
BECB/BEXD 



BTYP 



BLEN 



H- 



BDCB 
BARE 
BSTS/BLOG 












BKVS/BKEY 
BBLK/BEXI 






IOCB 
foundation 



BSAM 
DECB 



A 

I 
BDAM/BISAM 
DECB 






BDBF/BXLV 
(Reserved) 



BBBF 



A 
I 
I 
BDAM/BSAM 
Hidden 
buffer 
area 



Note: (The IOCB includes the Data Event Control Block (DECB) 
for the BSAM and BDAM/BISAM Interfaces) 

Figure 65. Format of the I/O Control Block (IOCB) 



BACT: One byte containing an activity flag 
(used only in direct access): 



Code 

X'FF* 

X'OO' 



Meaning 

In use 
Free 



BPIO: Chain-back address of the previous 
I/O control block. 

BNIO: Chain-forward address of the 
next I/O control block. 

BERR: Flag byte for record-oriented 
I/O situations: 
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Situation 



Code 



Name 



IOCB has been checked 0000 0001 BMCH 
I/O error exists 0000 0010 BMER 
End-of-file has 

occurred 0000 0100 BMEF 

Possible lock for 

REWRITE 0000 1000 BMPR 

Lock for 

REWRITE 0001 0000 BMNR 

IOCB for BISAM 

READ UPDATE mode 0100 0000 BMDF 
Dummy buffer acquired 1000 0000 BMDB 

BFCB: Address of the FCB for the file. 

BREQ: Request control block. Four- byte 
field specifying the request codes for 
associated operations (as passed by the 
compiled calling sequence) : 

Byte 1 Operation 



X'00' 


READ 


X'04* 


WRITE 


X'08» 


REWRITE 


X'OC 


DELETE 


X'10' 


LOCATE 


X'14* 


UNLOCK 


x*i8' 


WAIT 


Byte 2 


Option Set 1 


X'00' 


None/SET 


X'04' 


IGNORE 


x'08' 


INTO/FROM 


Byte 3 


Option Set 2 


X'00' 


None 


X'04' 


KEYTO 


x'08' 


NOLOCK 


Byte 4 


Option Set 3 



X'20' EVENT option 

X'40' VARYING record variable 

(INTO) 
X'80' VARYING KEYTO 

BERC/BEFC/BXTC/BKYC: Error codes for 
various conditions. 

BERC: ERROR condition 

BEFC: ENDFILE condition 

BXTC: TRANSMIT condition 

BKYC: KEY condition 

(See Chapter 6 for details of these 
codes . ) 

BRCC: Error code for RECORD condition. 
(See Chapter 6 for details of these 
codes . ) 



BRVS: Address of RDV or SDV for record 
variable. 

BEVN: Address of event variable; zero, if 
none exists for associated operation. 

BDF1/BBF1: 

BSAM: BDF1: Address of the user's 
record variable. 

BDAM: BBF1: Address of the user's 
record variable. 

BDF2/BBF2: 

BSAM: BDF2: Length, in bytes, of the 
user's record variable. 

BDAM: BBF2: Length, in bytes, of the 
user's record variable. 



BDF3: 



BSAM: Length, in bytes, of the KEYTO 
area. 

BDAM: (Reserved) 



BDF4/BBF3: 

BSAM: BDFM: Address of the KEYTO area. 

BDAM: BBF3: Relative record or track 
number (BLKREF) . 

BDF5: BSAM: Relative record number 
(REGIONAL (1)). 

BECB/BEXD: 

BECB: The data management event control 
block (ECB). 



BEXD: If BDAM is used, bytes 2 and 3 
(= BEXD) of this field contain 
the BDAM exception codes. For 
definitions of these codes, see 
IBM System/3 6 Operating System: 
Supervisor a n d Data Management 
Macro Instructions. 



BTYP: Type of I/O operation (set 
by data management macro) . 

BLEN: Length, in bytes, of the records to 
be transmitted. 

BDCB: Address of the DCB. 
BARE: 

Hidden buffers: Address of the 

appended buffer. 

No hidden buffers: Address of the record 

variable. 
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BSTS/BLOG: 

BSAM: BSTS; Address of the status 
indicator. 

BDAM: BLOG: Address of the IOB (I/O 
block? see IBM System/360 
Operating System; System 
Programmer's Guide . 

BISAM: BLOG: Address of the logical 
record. 

BKVS/BKEY 

BSAM: BKVS: Address of SDV for KEYTO. 

BDAM: BKEY: Address of KEY 

BBLK/BEXI : 

BBLK: Address of BLKREF, the relative 

record or track number (i.e., the 
address of BBF3) . 



BEXI: If BISAM is used* one byte 
(= BEXI) contains the BISAM 
exception codes. For definitions 
of these codes, see IBM 
System/360 Operating System: 
Supervisor and Data Management 
Macro Instructions . 



BDBF/BXLV: 



BSAM and BISAM: BDBF: Start of hidden 
buffer. 



BDAM: BXLV: Address of the exclusive 
block (if any) associated with 
record being referenced. 



BBBF: Start of BDAM/BISAM hidden buffer. 





j SEQUENTIAL 

l _ _ _ 




j DIRECT 


1 
j 








"T T 






| CONSECUTIVE | REGIONAL 




j REGIONAL | INDEXED 






| | (KEYED) 








H 


| | (1) (2) 

F-format j A j A j A j 


(3) 


| (1) (2) (3) | 

| A | A | A | A 


~H 


A 




records | B j B j B j 


B 


j C j C j C j C 






1 j 8 j D & j 


Da. 


1 8 | Da. | Da. | Da, 






1 1 1 D a | 


D a 


1 1 1 1 Da 
1 1 1 1 1* 




H 


V-format j A 1 ~ 1 1 




lilt (Note 1) 
| - | - | A | 


-H 


A 




records j B III 


B 


1 1 1 c | 






1 D a | | | 


Da. 


1 1 1 Dil 




f- 


U-format j A 1 " 1 1 


D a 


1 1 1 D a | 
| - | - | A | 


— * 


A 




records j B III 


B 

Da. 

D a 


1 1 | C j 

1 1 1 Da. | 














r 


A: Size of IOCB foundation 




|Note 1: If RKP * 0, then Da. = 


0.( 




B: Size Of BSAM DECB 




jlf RKP = then for blocked 






C: Size Of BDAM/BISAM DECB 




j records: Da. = L, and for 






D: Size of hidden buffer: 




(unblocked records: Da. = 2L, 






Da.: Length of recorded key 




(where L = length of recorded 






D a : Length of block (record) 




j key. 

JNote 2: The data value is ob- 
jtained by summing the sizes 
| given under each entry. 





Figure 66. Values used in Computing Size of IOCB for Various Access Methods 
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OPEN CONTROL BLOCK (OCB) 



4 



8 



12 



I Type j j Access j Mode j 



16 



20 



24 



28 



31 



r t r t t 

j Flag A j Flag B j Flag C j Flag D j 



Figure 67. Format of the Open Control 
Block (OCB) 



Type 




STREAM 




0001 






RECORD 




0010 


Acces 


ss 


SEQUENTIAL 


0001 






DIRECT 




0010 


Mode 




INPUT 

OUTPUT 

UPDATE 




0001 
0010 
0100 






BACKWARDS 


1000 


Flag 


A 


Bit: 



1 
2 
3 


KEYED 
EXCLUSIVE 
BUFFERED 
UNBUFFERED 


Flag 


B 







TRANSIENT 


Flag 


C 






(Reserved) 


Flag 





Bit: 



1 
2 
3 


(Reserved) 
PRINT 
(Reserved) 
(Reserved) 
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EXAMPLE OF CHAINING 



Figure 68 contains an example of the 
chaining of FCBs, IOCBs, event variables, 
and exclusive blocks in a single task. 



Files 



The task has opened two files, and the 
addresses of their FCBs (FCB1 and FCB2) are 
stored in the PRV; the FCBs are placed in a 
chain that is anchored in the 
pseudo- register IHEQFOP and uses the TFOP 
fields in the FCBs. The task also has 
access to another file that was opened in a 
higher task; the address of the FCB for 
this file (FCB3) was copied into the PRV 
when the task was attached. (Note that 
this FCB does not appear in the IHEQFOP 
chain. ) A DCLCB exists for each file 
declared, but only the one corresponding to 
FCB1 is shown in Figure 68; this file is an 
exclusive file that has been opened for 
DIRECT UPDATE. 



termination of the task, they can be set 
complete, inactive, and abnormal. (Note 
that the address in the chain- back field 
EVCB in event variable 1 is not that of 
IHEQEVT, but that of the field three words 
higher: IHEQEVT is thus in the same 
position relative to this address as EVCB 
is relative to the first byte of the event 
variable.) Event variables 1, 3, and 4 
relate to the file corresponding to FCB1, 
and must be set complete, inactive, and 
abnormal when the file is closed. 
Communication with event variables 1 and 3 
is established via the corresponding IOCBs. 
But event variable 4, which relates to an 
I/O operation for which an IOCB was not 
required, is placed in a chain anchored in 
the TEVT field of the FCB. Event variable 
2 is related to an I/O operation on another 
file in the task. 



Exclusi ve Blocks 



IOCBs 



Three of the current I/O operations that 
refer to FCB1 required IOCBs. The IOCBs 
are placed in a chain anchored in the TLAB 
field of the FCB so that they can be freed 
when the file is closed. The BXLV field in 
each IOCB addresses the corresponding 
exclusive block. The EVENT option was used 
with two of the I/O operations: the BEVN 
fields in IOCBs 1 and 3 therefore point to 
the corresponding event variables. (The 
third operation originated in another 
task.) 



Event Variables 



The task has four active I/O event 
variables. These are chained from the 
pseudo-register IHEQEVT so that, on 



For REGIONAL files and INDEXED files with 
unblocked records, an exclusive block 
exists for each record currently locked; 
all those shown refer to the file 
corresponding to FCB1. (If the files have 
blocked records, only one exclusive block 
exists for each file in each task; it is 
created the first time a record in the file 
is locked, and is not freed until the file 
is closed. ) The exclusive blocks are 
placed in a chain anchored in the TXLV 
field of the FCB so that the blocks can be 
freed when the file is closed. Only two of 
the records have been locked by this task, 
and their exclusive blocks (1 and 3) are 
placed in a chain anchored in 
pseudo- register IHEQXLV so that the records 
can be unlocked on termination of the task. 
(Note that the chain-back fields, XCBT and 
XCBF, in exclusive block 1 point, not to 
IHEQXLV and TXLV, but to fields in the PRV 
and FCB1 that have the same positions 
relative to IHEQXLV and TXLV as the start 
of the exclusive block has relative to XCBT 
and XCBF.) 
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A(FCB3) 
A(FCB2) 
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EXCLUSIVE 
BLOCKS 



© 



XCFF 



XCBF 
"XCTT 
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© 



XCFF 
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XCFT 
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© 



XCFF = 
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APPENDIX J: STORAGE-MANAGEMENT CONTROL BLOCKS 



This appendix gives the formats of the control blocks used by the non-multitasking 
storage-management modules of the PL/I Library; the formats of the multitasking 
equivalents are given in Appendix K. The functions of the blocks and the way they are 
used are described in Chapter 4. In the diagrams, all offsets are in hexadecimal. 
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AREA VARIABLE 



7 8 31 

r t 1 

| See Note | Length of Area Variable | 

U | Offset of End of Extent | 
k ) 

8 | Offset of Largest Free Element | 
^ ) 

C | See Note | 

,. ^ 

i i 

i i 

i i 

i i 

i i 

i i 

i i 

i i 

i i 

i j 

Note; If the area variable contains a free 
list, bit of the first byte is set 
to 1, and the fourth word is set to 
0. 

Figure 69. Format of Area Variable 
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DYNAMIC STORAGE AREA (DSA) 




4 
8 
C 

44 

48 
50 
58 



7 8 



31 



Flags j Length 

Chain-back address 
Chain-forward address 



I 



Register save area 






Current file 
Invocation count 



OPTIONAL ENTRIES: 



) 



Display 

Statement number 
ON fields 

Dope vectors 

AUTOMATIC data 
Workspace 
Parameter lists 









Figure 70. Format of the Dynamic Storage 
Area (DSA) 









T 
Bit | 

I - o 



Meaning 
Always = 1 



1 | No statement num- 
jber field in DSA 



2 (No dummy ON field 
j for STRINGRANGE 






3 (Procedure DSA 






| No dummy ON field 
for SUBSCRIPTRANGE 



I 






5 | Non-recursive DSA f 
j without display 
(update field 






6 | No ON fields 






7 | No dummy ON field 
| for SIZE 
I 



Statement number 
field in DSA 



STRINGRANGE field 
created as for 
other ON condi- 
tions 



Begin block DSA 



SUBSCRIPTRANGE 
field created as 
for other ON con- 
ditions 



Recursive DSA V 
with display up- 
date field 



ON fields 



SIZE field created 
as for other ON 
conditions 



Figure 71. Format of the DSA Flag Byte 



The minimum size of a non-multitasking 
DSA is X'64* bytes. 

Standard Entries 

Standard Save Area: The area starting with 
the flags and continuing up to and 
including the register save area. (see 
Figure 55 and associated text.) 

Current Files This field is eight bytes 
long; its use is described in 'Current 
File' in Chapter 3. In a multitasking 
environment, the first byte is used as the 
SYSPRINT resource counter; see 'SYSPRINT in 
Multitasking' in Chapter 3. 

Invocation Count: This field is eight bytes 
long and contains: 

1st word: Environment chain- back address or 
zero 

2nd word: Invocation count 



Optional Entries 

Display: This field is eight bytes long and 
contains : 

1st word: Pseudo-register offset 

2nd word: Pseudo-register update 

If it occurs at all, the display field 
always appears at offset 58. 

statement Number: This field is four bytes 
long; it is described in 'Error and 
Interrupt Handling* . If it occurs at all, 
the statement number always appears at 
offset 60; bytes 60-61 are always set to 
zero and bytes 62-63 contain the statement 
number in hexadecimal notation. If there 
is no statement number, this field can be 
used for optional DSA entries, e.g., ON 
fields. 

ON fields: Each ON field is two words long. 
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The ON fields are described in *ON 
Conditions* under 'Error and Interrupt 
Handling* . The position of the first ON 
field depends on whether there are entries 
in the display update and statement number 
fields : 

1. No display update, no statement 
number: ON fields begin at offset 58. 

2. Display update, but no statement 
number: ON fields begin at offset 60. 

3. Statement number (with or without a 
display update) : ON fields begin at 
offset 64. 



The last ON field is indicated by bit 
= 1 in the second word. 



Remaining Entries 



The dope vector formats are described in 
Appendix H ('Compiler-Generated Control 
Blocks*). The AUTOMATIC data, workspace 
and parameter lists areas are provided for 
use by the compiler. 
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VARIABLE DATA AREA (VDA) 



7 8 



31 



7 8 

0| Flags | 
t 



31 



Length 



Chain-back address 



H 8 






-H 



8| 



Data 



Figure 72. Format of the Variable Data 
Area (VDA) 



r t i 

0| Flags | Length(= L(PRV) ♦ L(LWS) ♦ 8) 
j. 



I Y 



A (External save area) 



Pseudo- register vector (PRV) 



Library workspace (LWS) 



LWF(DSA optimization area, 
OPT=01 only 



Figure 74. Format of the PRV VDA 



H 



■H 



._j 



7 8 



Bit 

0123 | H567 
+ 



+~ 



I 
0010 ioooo 

+ 

0010 I 0001 



* ^ 

0010|0101 



Meaning 



Ordinary VDA 1 



-H 



VDA obtained for a 
library subroutine 3 

VDA containing a 
secondary LWS 

| 0010 | 1001 | PRV VDA | 

Figure 73. Format of the VDA Flag Byte 



4 
8 

10 



Flags 



Length 



31 



f ± < 

Chain- back address 

Chain-back address 
(previous LWS) 
j. 4 

(unused) 
k 4 

Library workspace (LWS) 
j. 1 

LWF(DSA optimization area, 
OPT=01 only) 



Figure 75. 






Format of LWS VDA 



"•VDA obtained to hold automatic data declared with adjustable bounds or lengths. 

a VDA obtained for a library subroutine, or obtained by compiled code for a temporary data 
item. 
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APPENDIX K: MULTITASKING CONTROL BLOCKS 



This appendix describes the control blocks used by the multitasking storage-management 
modules of the PL/I Library. The way in which they are used by the library is described 
in Chapter 5. In the diagrams, all offsets are in hexadecimal. 
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CONTROL TASK STORAGE AREA 



48J- 



90 I- 



ACj- 



CC 



UCC 



Save Area 



Workspace 



Major Task Task Variable 



Major Task Event Variable 



ECBLIST 



CTECB 



-H 



H 



WORKSPACE: used by control task for 

(a) Parameter list for IHESUB 

(b) Parameter list for attach macro 

(c) Parameter list for IHETEXC 



ECBLIST: 256 words for a maximum of 256 

tasks. The last entry in contains 
X'80* in top byte. 

CTECB: the ECB posted by tasks after 
completion of "soft" code. 



._j 



UDOL 

Figure 76. Format of the Control Task Storage Area for Multitasking 
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DYNAMIC STORAGE AREA (DSA) 




4 
8 
C 

44 
48 

50 

58 

60 
64 
68 
6C 



7 8 

r 

Flags | Length 
l 

Chain-back address 



Chain- forward address 



Register save area 



Current file 



Invocation count 



Display 



Flags | 
j.. 



Statement number 



A (Task variable chain) 



Zero 



ON fields 
Dope vectors 
AUTOMATIC data 
Workspace 
Parameter lists 



31 



H 



-H 



H 



-H 



Figure 77. Format of the Dynamic Storage 
Area (DSA) for Multitasking 

The minimum size of a multitasking DSA 
is X'6C bytes. 

The multitasking DSA contains two fields 
that do not appear in the non- multitasking 
DSA (Appendix J) : the full word commencing 
at byte 64 contains the address of the 
first task variable in the task-variable 
chain (if any) ; the following fullword is 
always set to zero. The presence of a task 
variable chain is indicated by bit = 1 in 
byte 60. The Get DSA routine IHETSAD 
differs from its non-multitasking 
equivalent only in that it sets the 
doubleword commencing at byte 64 to zero. 
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EVENT VARIABLE 



7 8 



15 16 



23 24 



31 





4 

8 

C 

10 

14 

18 

1C 



Flags 



| Reserved 

i 

Internal PL/I ECB 
Reserved 



Reserved 



Status 



I 



| Statement Number 
x 

Reserved 



Reserved 
External ECB 
• Figure 78. Format of the Event Variable 
The task event variable is not chained. 
Flags : 

Flag 



Code 



Active event variable 1000 0000 
Dummy event variable obtained 

by control task 0100 0000 

Normal PL/I termination 0010 0000 

Abnormal PL/I termination 0001 0000 



Internal PL/I ECB ; This is the internal 
PL/I event control block. Bit is 
set to 1 when a WAIT macro instruction 
referring to this ECB is issued; bit 1 
is set to 1 when a POST macro 
instruction is issued. When a WAIT 
for a task event is specified, this 
ECB is waited on until posted by PL/I 
control task. 



Status : Normal status: set to zero. 
Abnormal status: set to 1. 



Statement Number : Number of the statement 
in which the task was attached. 



External ECB : This ECB is specified to the 
control program when the task is 
attached, when the task is detached, 
the control program posts this ECB. 
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PRV VDA 



7 8 



31 



Flags | 



Length of PRV VDA 



y x ^ 

A (External save area) 
|. 1 

Pseudo-register vector (PRV) 



A (Attaching 


DSA) 


A (Attaching 


PRV VDA) 


A (Task variable) 


A (Parameter 


list) 



Optional entries: 
ON field 
Parameter list 

j. \ 

| Library workspace (LWS) | 

l J 

Figure 79. Format of PRV VDA for 
Multitasking 

A PRV VDA for multitasking is identified 
by a 1 in the first bit of the length field 
(bit 8 of the PRV VDA). Like its 
non-multitasking counterpart (Appendix J), 
it contains the PRV and primary LWS and is 
chained back to the external save area. It 



differs in the settings of the flag byte 
and in the presence of the following 
additional fields immediately following the 
PRV: 



1st word: Chain back to the DSA of the 
attaching task. 

2nd word: Chain back to the PPV VDA of 
the attaching task. 

3rd word: Address of its own task 
variable. 

Mth word: Address of the parameter list 

for the called procedure; if no 
parameters are being passed, 
this word is set to zero. 

The following fields are omitted if there 
are no entries: 

ON field: When a subtask is attached, the 
entries in the ON field of the 
DSA of the attaching task are 
copied into this field. 

Parameter list: Parameter list for the 
called procedure. 

The settings of the flag byte are as 
follows: 

Major task X'29* 

Subtask X'2D' 

Subtask with entries 
in ON field X'2F' 
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TASK VARIABLE 



7 8 



15 16 



31 



r T 1 

j Flags j A(PRV VDA) 

4 | | A(TCB) 

8 | | ACSYMTAB entry) 

1 



10 



14 



A(Event variable) 



Limit priority | Dispatching 
| priority 



-H 



Chain- forward address 



+ ., 

18 | | Chain- back address 

i l j 

Figure 80. Format of the Task Variable 

The task variable contains the task 
control information required by the PL/I 
Library. To enable subtasks to be detached 
when the attaching task is terminated, all 
task variables activated in a task are 
placed in a chain anchored in the DSA of 
the attaching task. Only the first two 
bits of the flag bytes are used: 

Bit 1: = Task variable inactive (task 
not attached) 
1 = Task variable active 
Bit 2: = CALL with TASK variable 
specified 
1 = CALL without TASK variable 
specified 
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TASK COMMUNICATION AREA 



0r 

J PECB 
4} 

j PLIST 

j WECB 
C |. T 

| FLAGS | WORKSPACE 
1 o i J. 

• Figure 81. Format of the Task 
Communication Area 



The TCA contains the POST and WAIT ECBs 
required by tasks wishing to request 
control task facilities, e.g., CALL another 
task, change priorities, etc. 

PECB: task post ECB; posts code requesting 
control task action 



PLIST: parameter list passed to control 
task 

WECB: task wait ECB; waits until control 
task has accepted request. 



FLAGS 



= 1 



=0 



|BIT| 

1 o | 

L J._ 


Message 

Task 


_i 


PL/I 
Subtask 


- -4 


j BIT | 
1 1 1 

L i_ 


Task enqueued 
on control task 


-4--- 


Not 
enqueued 


_ j 


|BIT| 
1 2-6 j 

h +- 

JBITJ 
1 7 | 
L X_ 


Reserved 

Enqueued 
on IHEOPEN 


-+— 

.1. 


Reserved 

Not 
enqueued 


— ^ 
_ j 
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APPENDIX L; PL/I LIBRARY MODULE NAMES, MEMBER NAMES AND ALIASES 



This appendix contains a table listing the 
PL/I Library modules in alphabetical order 
along with their associated member names 
and aliases. For a description of each 
module, see Chapter 9, Module Summaries. 
In the interests of clarity, the preceding 
characters IHE f as indicated by the first 
entries, have been omitted. 



j Module Name | Member Name j 
j. + + 

DDO I DDOA 



Aliases 



— T 



| Module Name 
j. j 

j IHEABN 


| Member Name 
| IHEABN 


Aliases | 
None j 


j ABU 


| ABUO 


m 1 


j ABV 


ABVO 


* 1 


j ABW 


ABWO 


«• j 


| ABZ 


| ABZO 


M 1 


j ADD 


i ADDO 


n j 


| ADV 


| ADVO 


N I 


j APD 


| APDA 


APDB | 


j ATL 


ATLU 


ATLl , j 
2 & 3 | 


| ATS 


| ATSl 


ATS 2, 3 | 

C 4 | 


| ATW 


| ATWN 


ATWH j 


j ATZ 


| ATZN 


ATZH j 


j BEG 


BEGN 


BEGA j 


j BSA 


BSAO | 


None j 


j BSC 


BSCO 


m 1 


| BSD 


| BSDO 1 


" 1 


j BSF 


BSFO 


m 1 


j BSI 


BSIO ! 


a 1 


j BSK 


BSKK | 


BSKA, | 
BSKR | 


| BSM 


BSMF | 


BSMV, j 
BSMZ j 


| BSN 


BSNO | 


None | 


j BSO 


BSOO | 


« 1 


j BSS 


BSS 2 | 


BSS3 | 


j BST 


BSTA | 


None | 


j BSV 


BSVA | 


" I 


j CFA 


CFAA | 


N 1 


| CFB 


CFBA | 


H 1 


| CFC 


CFCA | 


m 1 


j CKP 


CKPT I 


m 1 


j CLT 


CLTA | 


CLTB | 


| CNT 


CNTA | 


CNTB | 


| CSC 


CSCO | 


None j 


j CSI 


CSIO | 


M 1 


j CSK 


CSKK | 


CSKR | 


| CSM 


CSMF 


None j 


| CSS 


CSS 2 | 


CSS3 j 


j CST 


CSTA | 


None j 


j CSV 


CSVA | 


■ | 


j CTT 


CTTA | 


CTTB, | 
CTTC j 


| DBN 


DBNA | 


DBN j 


j DCN 


DCNA | 


DCN, | 
DCNB j 


| DDI 


DDIA | 


DDIB | 


j DDJ 


DDJA | 


DDJ j 


L_— ______—__— J 




.—_-.—___—____ J 



DDP 



DDT 



DIA 

DIB 
DID 
DIE 
DIL 
DIM 
DMA 
DNB 
DNC 
DOA 

DOB 

DOD 
DOE 
DOM 
DSP 
DUM 



DVU 
DW 
DZW 
DZZ 
EFL 
EFS 
ERD 
ERE 
ERI 
ERO 
ERP 
ERR 



ERT 
ESM 
EXL 
EXS 
EXW 
EXZ 
HTL 
HTS 
IBT 



DDPA 



DDTA 



DIAA 

DIBA 
DIDA 
DIEA 
DILA 
DIMA 
DMAA 
DNBA 
DNCA 
DOA A 

DOBA 

DODA 
DOEA 
DOMA 
DSPA 
DUMP 



DVUO 
DWO 
DZWO 
DZZO 
EFLC 
EFSF 
ERDA 
EREA 
ERI A 
EROA 
ERPA 
ERRA 



ERTA 
ESMA 
EXLO 
EXSO 
EXWO 
EXZO 
HTLO 
HTSO 
IBT A 



IBTB, 
IBTC, 
IBTD, 
IBTE 



DDOB, 

DDOC, 

DDOD, 

DDOE 

DDPB, 

DDPC, 

DDPD 

DDTB, 

DDTC, 

DDTD, 

DDTE 

DIA, 

DIAB 

DIBB 

None 

DIE 

DILB 

None 

DMA 

DNB 

DNC 

DOA, 

DOAB 

DOBB, 

DOBC 

DODB 

DOE 

None 

n 

DUMC, 
DUMJ, 
DUMT 
None 



EFLF 
EFSC 
None 



ERRB, 

ERRC, 

ERRD 

None 

ESMB 

None 



■H 
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| Module Name | Member Name | 



INT 
IOA 



IOB 



IOC 

IOD 
IOF 
ION 
I OP 

I OX 

ITB 
ITC 
ITD 
ITE 
ITF 
ITG 
ITH 
IT J 
ITK 
ITL 
ITP 
JXI 
JXS 
KCA 
KCB 
KCD 

LDI 



LDO 

LNL 

LNS 

LNW 
LNZ 
LSP 

LTT 



LTV 
MAI 
MPU 
MPV 
MSI 
MST 
MSW 
MXB 
MXD 
MXL 
MXS 
MZU 
MZV 



I NT A 
IOAA 



I OB A 



I OCA 

I0D6 
I OF A 
IONA 
IOPA 

IOXA 

ITB A 
ITCA 
ITD A 
I TEA 
ITFA 
ITGA 
ITHA 
ITJA 
ITKA 
I TLA 
ITPA 
JXII 
JXS I 
KCAA 
KCBA 
KCDA 

LDIA 



LDOA 

LNLZ 

LNSZ 

LNWO 
LNZO 
LSPA 



LTTA 
LTTB 
LTTC 
LTVA 
MAIN 
MPUO 
MPVO 
MSIA 
MSTA 
MSWA 
MXBX 
MXDX 
MXLX 
MXSX 
MZUM 
MZCM 



Aliases | 

None 

10 AB, 

IOAC, 

IOAD 

IOBB, 

IOBC, 

IOBD, 

IOBE 

IOCB, 

IOCC 

IODP 

None 

n 

IOPB, 
IOPC 
IOXB, 
IOXC 

None 



JXIY 

JSXY 

KCA 

KCB 

KCD, 

KCDB 

LDIB, 

LDIC, 

LDID 

LDOB, 

LDOC 

LNLD, 

LNLE 

LNSD, 

LNSE 

None 

n 

LSPB. 
LSPC, 
LSPD 
None 



MXBN 
MXDN 
MXLN 
MXSN 
MZUD 
MZVD 



| Module Name j Member Name j 






MZW 
MZZ 
M91 



NLl 
NL2 
OCL 

OCT 



OPN 
OPO 
OPP 
OPQ 
OPZ 
OSD 
OSE 
OSI 
OSS 
OST 
OSW 
PDF 
PDL 
PDS 
PDW 
PDX 
PDZ 
PRT 
PSF 
PSL 
PSS 
PSW 
PSX 
PSZ 
PTT 
RES 
SAP 



SHL 
SHS 
SIZ 
SMF 
SMS 
SMH 
SMX 
SNL 



SNS 



SNW 



SNZ 






MZWO 
MZZO 
M91A 



NL1N 
NL2N 
OCLA 

OCTA 



OPNA 
OPOA 
OPPA 
OPQA 
OPZA 
OSD A 
OSEA 
OSIA 
OSSA 
OSTA 
OSWA 
PDFO 
PDLO 
PDSO 
PDWO 
PDXO 
PDZO 
PRTA 
PSFO 
PSLO 
PSSO 
PS WO 
PSXO 
PSZO 
PTTA 
REST 
SAPA 



SHLS 
SHSS 
SIZE 
SMFO 
SMSC 
SMHC 
SMXO 
SNLK 



SNSS 



SNWK 



SNZK 



Aliases j 

None 

• 

M91, 

M91B, 

M91C 

LN1A, 

NL1L 

NL2A. 

NL2L 

OCLB, 

OCLC, 

OCLD 

OCTB, 

OCTC, 

OCTD 

None 



PRTB 
None 






PTTB 

RESN 

SAPB, 

SAPC, 

SAPD, 

SADA 

SHLC 

SHSC 

None 

m 

SMGR 

SMHR 

None 

SNLC, 

SNLS, 

SNLZ 

SNSC, 

SNSK, 

SNSZ 

SNNC f 

SNWS, 

SNWZ 

SNZC, 

SNZS, 

SNZZ 
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r" 

1 

h 


Module Name j Member Name j Aliases j 
i i i 


j Module Name j 
j. x. 

| VPC j 


Member Name j Aliases j 
VPCA | VPC | 


SPR | 


SPRT 


None | 




SQL | 


SQL0 


m ■ 


j VPD j 


VPDA | 


VPD j 




SQS | 


SQSO 


* 1 


j VPE | 


VPEA 


VPE | 




SQW | 


SQWO 


m i 


| VPF j 


VPFA 


VPF j 




SQZ 


SQZO 


m | 


j VPS | 


VPGA 


VPG | 




SRC j 


SRCA 


SRCB, | 


| VPH j 


VPHA 


VPH j 








SRCC, j 


1 VQA | 


VQAA 


None j 








i SRCD, | 


1 VQB | 


VQBA 


VQB | 








SRCE j 


1 VQC j 


VQCA 


VQC j 




SRD | 


SRDA 


None j 


j VSA j 


VSAA 


VSA | 




SRT | 


SRTA 


SRTB, | 


j VSB j 


VSBA 


VSB j 








SRTC, j 


j VSC | 


VSCA 


VSC | 








SRTD | 


| VSD j 


VSDA 


VSD, j 




SSF | 


SSFO 


None | 






VSDB | 




SSG | 


SSGC 


SSGR j 


| VSE | 


VSEA 


VSE, | 




SSH | 


SSHC 


SSBR j 






VSEB | 




SSX | 


SSXO 


None j 


| VSF | 


VSFA 


VSF j 




STA | 


STAA 


" 1 


j VTB | 


VTBA 


None | 




STG | 


STGA 


| STGB | 


j XIB j 


XIBO 






STP 


STPA 


None | 


j XID | 


XIOO 






STR | 


STRA 


STRB, j 
STRC j 


1 XIL j 
j XIS j 


XILO 
XISO 






SUB | 


SUBA 


None j 


1 xio | 


XIOO 






TAB j 


TABS 


N 1 


j XIV j 


XIVO 






TCV 


TCVA 


TCVB | 


1 xiw | 


XI WO 






TEA | 


TEAA 


None j 


1 xiz j 


XIZO 






TER 


TERA 


TER j 


j XXL | 


XXLO 






TEV | 


TEVA 


None | 


j XXS j 


XXSO 






TEX | 


TEXA 


TEXB, j 
TEXC j 


j XXW | 
j XXZ | 


xxwo 
xxzo 






THL | 


THLO 


None j 


j YGF | 


YGFV 


YGFS | 




THS | 


THSO 


m t 


1 YGL | 


YGLV 


YGLS | 




TNL | 


TNLD 


TNLR | 


j YGS j 


YGSV 


YGSS j 




TNS | 


TNSD 


TNSR j 


j YGW | 


YGWV 


| YGWS | 




TNW | 


TNWH 


TNWN j 


| YGX j 


YGXV 


YGXS j 




TNZ j 


TNZH 


TNZN j 


j YGZ | 


YGZV 


| YGZS j 




TOM | 


TOMA 


TOMB, | 


| ZZA j 


ZZAA 


None j 








TOMC, j 


j ZZB | 


ZZBA 


1 " 1 








TOMD j 


| ZZC j 


ZZC A 


n I 




TPB | 


TPBA 


None | 


j ZZF j 


ZZFA 


m ■ 




TRP j 


TPRA 


m 1 


t___ __- .__ — X- 


-____________x___ — ___ — ___i 




TSA j 


TSAP 


TSAA, | 
TSAB, | 
TSAD, j 
TSAO | 










TSE | 


TSEA 


None j 










TSS | 


TSSA 


m 1 










TSW j 


TSWA 


m | 










UPA | 


UPAA 


UPAB | 










UPB j 


OPBA 


UPBB | 










VCA | 


VCAA 


VCA | 










VCS | 


VCSA 


VCS, j 
VCSB | 










VFA | 


VFAA 


VFA | 










VFB | 


VFBA 


VFB j 










VFC | 


VFCA 


VFC | 










VFD | 


VFDA 


VFD j 










VFE j 


VFEA 


VFE \ 










VKB j 


VKBA j 


VKB | 










VKC | 


VKCA 


VKC j 










VKP | 


VKFA 1 


VKF j 










VKG | 


VKGA ! 


VKG j 










VPA j 


VPAA 


VPA | 








1 


VPB j 


VPBA | 


VPB | 








L. 






■ 
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INDEX 

Indexes to program logic manuals are consolidated in the publication IBM System/360 
Operating System; Program Logic Manual Index , Form Y28-6717. For additional information 
about any subject listed below, refer to other publications listed for the same subject 
in the Master Index. 

(Where more than one page reference is given, the major reference is first.) 



•anchor word' 46 
•bootstrap* routine 20 
•call sets, 25 
•check bit f (EMCH) 63 
•complete bit' (ECMP) 63 
•complete bit* (event variable) 62 
•mother- daughter* relationship 59 
•extended search • feature 39 
• soft • code 55 

A format items 81 
ABEND macro 43 
abnormal return 79 
abnormal termination 70 
abnormal- end-of -task routine 61 
access method interfaces 

CONSECUTIVE data sets 
BSAM 34 
QSAM 34 

INDEXED data sets 
BISAM 35 
QISAM 35 

REGIONAL data sets 
BDAM 37 
BSAM 37 
additional access modules, record I/O 32 
address of current LWS 44 
addressing interrupt 66 
ADV (Array Dope Vector) 14,84-85 
ADV field definition 183 
aliases of modules 247 
alignment, (fixed/ varying strings) 79 
alignment of modules 177 
ALL (arrays) 84-85 
ALLOCATE statement 45 
allocation request 46 

alternative I/O modules (multitasking) 63 
ANY (arrays) 84-85 
APLIST (parameter list) 57 
area storage for based variables 48 
area variable 48,227 
area variable assignment 48 
AREA 

alignment 48 

attribute 46 

based- variables, extent 48 

condition 48 
arguments 

array 14 

conversion of 83-84 

evaluation of 83-84 

in mathematical subroutines 83-84 

scalar 14 
arithmetic assignment, function and 

operations 83-84 
arithmetic conversions and editing 80 



arithmetic data representation 13 
arithmetic target fields 87 
array dope vector (ADV) 14,84-85 
array dope vector (ADV) field 

definition 183 
array functions 83 
array functions 

ALL 84-85 

ANY 84-85 

POLY 8 4-85 

PROD 84-85 

SUM 84-85 

value returned 84-85 
array element address 183 
array, storage 18 3 
arrays 

interleaved 84-85 

simple 84-85 
assignment of area variables 48 
ATTACH (post code) 57 
attach subroutine 58 
automatic restart 16 
automatic storage 43 
automatic storage 

allocation 44 

allocation requirements 44 

chain-back 44 

freeing 44 
automatic transmission 34 



B format items 81 
based-variables 
allocation 46 
area storage 
allocate 48 
element 48 
free elements 48 
free list 48 
offset 48 
system storage 46 
BCD name, address and length 70 
BDAM BLKREF parameter 37 
BDAM 

CHECK macro 39 
DIRECT access of REGIONAL 39 
TASK option 39 
BISAM 

multitasking 

blocked records 37 
unblocked records 36 
non-multitasking 
DELETE 36 
exclusive 36 
KEY 36 
KEYFROM 36 
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READ 36 
UNLOCK 36 
VwUTE 36 
bit functions, byte aligned 8 5-86 
bit string conversion 84-85 
bit string/picture character- string 

conversion 82 
block header statement 68 
block housekeeping 42 

epilogues 42 

object program management 50 

prologues 12 
blocks, non-recursive/recursive 43 
BOOL function 85-86 
BSAM 

creation and access 

DIRECT creation 38 

DIRECT initialization 38 

error ONCODE 38 

F- format records 35 

LOCATE 38 

overlap of transmission 34 

READ SET 39 

SEQUENTIAL access of REGIONAL 38 

UNBUFFERED 34 

V- format records 35 
built-in functions (multitasking) 62 
built-in functions 

DATE 74 

ONCODE 70 

ONLOC 70 

TIME 74 
byte-aligned bit functions 85-86 



C format item 79 

CAD (Coded Arithmetic Data Item) 12 

CALL 

with EVENT option 59 

with PRIORITY option 59 

with TASK option 59 
calling sequence, PL/I 11 
chain-back address 12 
chaining of control blocks 223-224 
chaining of IOCB*s 205 
change data (internal) 79 
change, priority 62 
CHAP (change priority) macro 62 
character string/arithmetic conversion 81 
character string/bit string conversion 81 
character string/picture character string 

conversion 81 
CHECK option 24 
CHECKPOINT/RESTART 16 
CLOSE functions 

EXPLICIT 20 

IMPLICIT 22 
close process 

explicit 22 

implicit 22 
close QSAM data sets 34 
coded arithmetic data item (CAD) 12 
coding conventions 12 
communication conventions 14 
communication mode 

explicit 14 

implicit 14 
compatibility 



modular 177 

PL/I library 9 
compiled code, edit-directed 27 
COMPLETION pseudo- variable 62 
complex arguments 87 
complex directors 76 
complex-to-string directors 77-78 
computational subroutines 8 2 
computer-generated control blocks 181 
conditions other than on-conditions 70 
control blocks 14 
control blocks 

computer- generated 181 

input/output 217-219 

multitasking 233 

record I/O 32 
control length allocation request 46 
control program interfaces 87 
control task defined 54 
control task ECB (CTECB) 55 
control task storage area 235 
control task 

format 55 

lengths of areas 55 

priority 55 

save area 55 

subroutines 57 

workspace 55 
CONTROLLED attribute 62 
controlled storage 45 
controlled storage (multitasking) 62 
conventions 

coding 12 
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